docs: enhance README with detailed quick start guide and feature descriptions

Author: allmonday

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+
+## 0.11.0
+
+- Update README.md to emphasize rapid development of minimum viable systems
+- Add 30-Second Quick Start section for quick onboarding
+- Embed GraphiQL HTML template into the library
+- Add `get_graphiql_html()` method to `GraphQLHandler` with configurable `endpoint` parameter
+
 ## 0.10.0
 
 - add `allow_mutation` option to `create_mcp_server` to enable mutation support in the generated GraphQL server. This allows clients to perform create, update, and delete operations on the data models defined in the SQLModel schema.

README.md

@@ -5,21 +5,75 @@
 [![PyPI Downloads](https://static.pepy.tech/badge/sqlmodel-graphql/month)](https://pepy.tech/projects/sqlmodel-graphql)
 ![Python Versions](https://img.shields.io/pypi/pyversions/sqlmodel-graphql)
 
-**Generate GraphQL APIs & MCP from SQLModel — zero configuration required**
+**From SQLModel to Running GraphQL API + MCP Server in Minutes**
+
+sqlmodel-graphql is the fastest way to build a minimum viable system:
+
+- **Zero Config GraphQL** - SQLModel classes → GraphQL schema automatically
+- **@query/@mutation Decorators** - Mark methods, get endpoints instantly
+- **GraphiQL Built-in** - Interactive debugging playground
+- **One-Line MCP Server** - Expose APIs to AI assistants
+- **Auto N+1 Prevention** - Query optimization handled for you
 
 No schema files. No resolvers. No boilerplate.
+Just add decorators to your SQLModel classes.
+
+## 30-Second Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel
+from sqlmodel import SQLModel, Field, select
+from sqlmodel_graphql import query, GraphQLHandler
+
+# 1. Define your model with @query decorator
+class User(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+
+    @query
+    async def get_all(cls) -> list['User']:
+        async with get_session() as session:
+            return (await session.exec(select(cls))).all()
 
-Just decorators and Python. Your SQLModel classes become GraphQL APIs instantly.
+# 2. Create GraphQL handler (auto-generates schema)
+handler = GraphQLHandler(base=SQLModel)
 
-Plus: expose your GraphQL via MCP to AI assistants (Claude, GPT, etc.) with **three-layer progressive disclosure** — AI discovers what's available, understands the schema, then executes queries efficiently.
+# 3. Setup FastAPI endpoints
+class GraphQLRequest(BaseModel):
+    query: str
+    variables: dict | None = None
+
+app = FastAPI()
+
+@app.get("/graphql", response_class=HTMLResponse)
+async def graphiql():
+    return handler.get_graphiql_html()
+
+@app.post("/graphql")
+async def graphql(req: GraphQLRequest):
+    return await handler.execute(req.query, req.variables)
+```
+
+Run: `uvicorn app:app` and visit `http://localhost:8000/graphql` for the interactive playground.
 
 ## Features
 
-- **Automatic SDL Generation**: Generate GraphQL schema from SQLModel classes
-- **@query/@mutation Decorators**: Mark methods as GraphQL operations
-- **Query Optimization**: Parse GraphQL queries to generate optimized SQLAlchemy queries
-- **N+1 Prevention**: Automatic `selectinload` and `load_only` generation
-- **MCP Integration**: Expose GraphQL as MCP tools with progressive disclosure for minimal context usage
+### Rapid Development
+- **Zero Config GraphQL** - SQLModel classes become GraphQL schema automatically
+- **@query/@mutation Decorators** - Mark methods as GraphQL operations
+- **GraphiQL Integration** - Built-in playground for testing and debugging
+
+### Smart Optimization
+- **Auto N+1 Prevention** - `selectinload` and `load_only` generated automatically
+- **Query-Aware Loading** - Only fetch requested fields and relationships
+- **QueryMeta Injection** - Framework analyzes queries and optimizes database calls
+
+### AI-Ready with MCP
+- **One-Line MCP Server** - `config_simple_mcp_server(base=BaseEntity)`
+- **Progressive Disclosure** - AI discovers schema, understands, then queries
+- **Multi-App Support** - Serve multiple databases through one MCP server
 
 ## Installation
 
@@ -439,6 +493,10 @@ result = await handler.execute("{ users { id name } }")
 
 # Get SDL
 sdl = handler.get_sdl()
+
+# Get GraphiQL HTML (for interactive playground)
+html = handler.get_graphiql_html()  # defaults to /graphql endpoint
+html = handler.get_graphiql_html(endpoint="/api/graphql")  # custom endpoint
 ```
 
 **Auto-Discovery Features:**

demo/app.py

@@ -15,163 +15,6 @@
 from demo.models import BaseEntity
 from sqlmodel_graphql import GraphQLHandler
 
-# GraphiQL HTML (loaded via CDN)
-GRAPHIQL_HTML = """
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>GraphiQL - SQLModel GraphQL Demo</title>
-  <style>
-    body { margin: 0; }
-    #graphiql { height: 100dvh; }
-    .loading {
-      height: 100%;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      font-size: 2rem;
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-    }
-  </style>
-  <link rel="stylesheet" href="https://esm.sh/graphiql/dist/style.css" />
-  <link rel="stylesheet" href="https://esm.sh/@graphiql/plugin-explorer/dist/style.css" />
-  <script type="importmap">
-    {
-      "imports": {
-        "react": "https://esm.sh/react@19.1.0",
-        "react/jsx-runtime": "https://esm.sh/react@19.1.0/jsx-runtime",
-        "react-dom": "https://esm.sh/react-dom@19.1.0",
-        "react-dom/client": "https://esm.sh/react-dom@19.1.0/client",
-        "@emotion/is-prop-valid": "data:text/javascript,",
-        "graphiql": "https://esm.sh/graphiql?standalone&external=react,react-dom,@graphiql/react,graphql",
-        "graphiql/": "https://esm.sh/graphiql/",
-        "@graphiql/plugin-explorer": "https://esm.sh/@graphiql/plugin-explorer?standalone&external=react,@graphiql/react,graphql",
-        "@graphiql/react": "https://esm.sh/@graphiql/react?standalone&external=react,react-dom,graphql,@emotion/is-prop-valid",
-        "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit?standalone&external=graphql",
-        "graphql": "https://esm.sh/graphql@16.11.0"
-      }
-    }
-  </script>
-</head>
-<body>
-  <div id="graphiql">
-    <div class="loading">Loading GraphiQL...</div>
-  </div>
-  <script type="module">
-    import React from 'react';
-    import ReactDOM from 'react-dom/client';
-    import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
-    import { createGraphiQLFetcher } from '@graphiql/toolkit';
-    import { explorerPlugin } from '@graphiql/plugin-explorer';
-
-    const fetcher = createGraphiQLFetcher({ url: '/graphql' });
-    const plugins = [HISTORY_PLUGIN, explorerPlugin()];
-
-    function App() {
-      return React.createElement(GraphiQL, {
-        fetcher: fetcher,
-        plugins: plugins,
-        defaultQuery: `# Welcome to SQLModel GraphQL Demo!
-#
-# Try these queries:
-
-# Get all users
-query GetUsers {
-  users(limit: 10) {
-    id
-    name
-    email
-  }
-}
-
-# Get users with their posts (relationship)
-query GetUsersWithPosts {
-  users(limit: 5) {
-    id
-    name
-    email
-    posts {
-      id
-      title
-      content
-    }
-  }
-}
-
-# Get a specific user by ID
-query GetUser {
-  user(id: 1) {
-    id
-    name
-    email
-  }
-}
-
-# Get all posts
-query GetPosts {
-  posts(limit: 10) {
-    id
-    title
-    content
-    author_id
-  }
-}
-
-# Get posts with their authors (relationship)
-query GetPostsWithAuthors {
-  posts(limit: 5) {
-    id
-    title
-    content
-    author {
-      id
-      name
-      email
-    }
-  }
-}
-
-# Get posts by author
-query GetPostsByAuthor {
-  posts_by_author(author_id: 1, limit: 10) {
-    id
-    title
-    content
-  }
-}
-
-# Create a new user
-mutation CreateUser {
-  create_user(name: "Charlie", email: "charlie@example.com") {
-    id
-    name
-    email
-  }
-}
-
-# Create a new post
-mutation CreatePost {
-  create_post(title: "My New Post", content: "Hello GraphQL!", author_id: 1) {
-    id
-    title
-    content
-    author_id
-  }
-}
-`
-      });
-    }
-
-    const container = document.getElementById('graphiql');
-    const root = ReactDOM.createRoot(container);
-    root.render(React.createElement(App));
-  </script>
-</body>
-</html>
-"""
-
 
 class GraphQLRequest(BaseModel):
     """GraphQL request model."""
@@ -213,7 +56,7 @@ async def lifespan(app: FastAPI):
 @app.get("/graphql", response_class=HTMLResponse)
 async def graphiql_playground():
     """GraphiQL interactive query interface."""
-    return GRAPHIQL_HTML
+    return handler.get_graphiql_html()
 
 
 @app.post("/graphql")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlmodel-graphql"
-version = "0.10.0"
+version = "0.11.0"
 description = "GraphQL SDL generation and query optimization for SQLModel"
 authors = [{ name = "tangkikodo", email = "allmonday@126.com" }]
 readme = "README.md"

src/sqlmodel_graphql/__init__.py

@@ -31,7 +31,7 @@ async def get_all(cls, query_meta: QueryMeta = None) -> list['User']:
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.11.0"
 
 from sqlmodel_graphql.decorator import mutation, query
 from sqlmodel_graphql.handler import GraphQLHandler

src/sqlmodel_graphql/graphiql.py

@@ -0,0 +1,68 @@
+"""GraphiQL HTML template for SQLModel GraphQL."""
+
+GRAPHIQL_HTML = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>GraphiQL - SQLModel GraphQL</title>
+  <style>
+    body { margin: 0; }
+    #graphiql { height: 100dvh; }
+    .loading {
+      height: 100%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 2rem;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    }
+  </style>
+  <link rel="stylesheet" href="https://esm.sh/graphiql/dist/style.css" />
+  <link rel="stylesheet" href="https://esm.sh/@graphiql/plugin-explorer/dist/style.css" />
+  <script type="importmap">
+    {
+      "imports": {
+        "react": "https://esm.sh/react@19.1.0",
+        "react/jsx-runtime": "https://esm.sh/react@19.1.0/jsx-runtime",
+        "react-dom": "https://esm.sh/react-dom@19.1.0",
+        "react-dom/client": "https://esm.sh/react-dom@19.1.0/client",
+        "@emotion/is-prop-valid": "data:text/javascript,",
+        "graphiql": "https://esm.sh/graphiql?standalone&external=react,react-dom,@graphiql/react,graphql",
+        "graphiql/": "https://esm.sh/graphiql/",
+        "@graphiql/plugin-explorer": "https://esm.sh/@graphiql/plugin-explorer?standalone&external=react,@graphiql/react,graphql",
+        "@graphiql/react": "https://esm.sh/@graphiql/react?standalone&external=react,react-dom,graphql,@emotion/is-prop-valid",
+        "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit?standalone&external=graphql",
+        "graphql": "https://esm.sh/graphql@16.11.0"
+      }
+    }
+  </script>
+</head>
+<body>
+  <div id="graphiql">
+    <div class="loading">Loading GraphiQL...</div>
+  </div>
+  <script type="module">
+    import React from 'react';
+    import ReactDOM from 'react-dom/client';
+    import { GraphiQL } from 'graphiql';
+    import { createGraphiQLFetcher } from '@graphiql/toolkit';
+    import { explorerPlugin } from '@graphiql/plugin-explorer';
+
+    const fetcher = createGraphiQLFetcher({ url: '{graphql_url}' });
+
+    function App() {
+      return React.createElement(GraphiQL, {
+        fetcher: fetcher,
+        plugins: [explorerPlugin()]
+      });
+    }
+
+    const container = document.getElementById('graphiql');
+    const root = ReactDOM.createRoot(container);
+    root.render(React.createElement(App));
+  </script>
+</body>
+</html>
+"""

src/sqlmodel_graphql/handler.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING, Any
 
 from sqlmodel_graphql.discovery import EntityDiscovery
+from sqlmodel_graphql.graphiql import GRAPHIQL_HTML
 from sqlmodel_graphql.introspection import IntrospectionGenerator
 from sqlmodel_graphql.query_parser import QueryParser
 from sqlmodel_graphql.scanning import MethodScanner
@@ -93,6 +94,17 @@ def get_sdl(self) -> str:
         """
         return self._sdl_generator.generate()
 
+    def get_graphiql_html(self, endpoint: str = "/graphql") -> str:
+        """Get the GraphiQL HTML template.
+
+        Args:
+            endpoint: GraphQL API endpoint URL. Defaults to "/graphql".
+
+        Returns:
+            HTML string for GraphiQL playground.
+        """
+        return GRAPHIQL_HTML.replace("{graphql_url}", endpoint)
+
     async def execute(
         self,
         query: str,