easy-mcp-kit 0.2.2__tar.gz → 0.2.4__tar.gz

{easy_mcp_kit-0.2.2 → easy_mcp_kit-0.2.4}/.github/workflows/ci.yml

@@ -6,21 +6,26 @@ on:
     tags: ["v*"]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install
         run: pip install -e .[dev]
       - name: Lint
         run: ruff check easy_mcp tests
+      - name: Type check
+        run: mypy easy_mcp
       - name: Test
         run: pytest -q
 
@@ -35,8 +40,8 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Build sdist and wheel
@@ -44,4 +49,4 @@ jobs:
           pip install build
           python -m build
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

easy_mcp_kit-0.2.4/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to `easy-mcp-kit` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/); the public API is not frozen until 1.0.
+
+## [0.2.4] - 2026-09-23
+
+### Added
+
+- Parameter descriptions from `Annotated[T, "description"]`, alongside the
+  docstring's `Args:` section. The annotation sits next to the parameter, so it
+  cannot quietly stop applying when the parameter is renamed; where both exist,
+  the annotation wins. Nested forms such as `list[Annotated[int, "a row id"]]`
+  are described too.
+
+- Structured tool results. A tool whose return annotation describes a JSON object
+  now publishes an `outputSchema` in `tools/list` and answers with
+  `structuredContent` alongside the existing text block, which the spec keeps for
+  older clients. `output_schema={...}` declares one by hand and `output_schema={}`
+  opts out.
+
+  Only object-shaped returns qualify, because `structuredContent` is a JSON
+  object; `-> str` and `-> list[int]` tools are untouched. A missing or
+  unsupported return annotation is not an error -- return types were never
+  validated before, so tools that have worked since 0.1 keep working, just
+  without a schema.
+
+  Results are validated against the schema before they are sent, since the spec
+  requires a server to honour the shape it advertised. A tool that breaks its own
+  contract fails the call with an `error_id`; the offending data goes to the log,
+  not to the client.
+
+- Optional Pydantic v2 support for complex parameters and results, via the new
+  `easy-mcp-kit[pydantic]` extra. A parameter annotated with a model advertises
+  the model's own JSON Schema, constraints included, and reaches the tool as a
+  validated instance; a model return type becomes the `outputSchema`, and the
+  tool may return an instance or any dict the model accepts.
+
+  Pydantic validates the inside of a model rather than the built-in validator,
+  so a client sees every violation Pydantic finds instead of the first one a
+  weaker second copy of its rules would hit. Unknown top-level arguments are
+  still refused as before.
+
+  `easy_mcp` never imports Pydantic -- models are recognised by duck typing --
+  so projects that do not use it neither pay for the import nor install it.
+
+  Two cases are refused at registration: a model nested inside another type
+  (`list[User]`), and two different models sharing a class name in one tool.
+  Both would need `$defs` hoisted out of an ambiguous position.
+
+- `easy-mcp run my_tools:server`, a command that imports a module and serves the
+  server it defines, so a module of `@server.tool` functions needs no `__main__`
+  block to be launchable. The target resolves from the current directory and
+  `my_tools.py:server` is accepted too; the attribute defaults to `server` and may
+  be a callable returning one. `--transport` picks stdio or HTTP per host, and
+  `--host`, `--port` and `--debug` override the server's own constructor arguments
+  only when given.
+
+### Fixed
+
+- An `Annotated` parameter's description no longer vanishes from the generated
+  schema. `get_type_hints()` strips annotation metadata unless asked not to, so
+  the text was silently dropped and clients saw an undocumented parameter.
+
+## [0.2.3] - 2026-09-13
+
+### Added
+
+- Ready-made connectors, each a normal `MCPServer` built with `@server.tool` and
+  launchable with one command:
+  - **GitHub** (`easy-mcp-github`): repositories, issues, pull requests and file
+    contents through a `GITHUB_TOKEN` read from the environment, using only the
+    standard library for HTTP. Read-only by default; `--allow-write` adds
+    `create_issue` and `comment_on_issue`, gated by the `github:write` scope.
+  - **Postgres** (`easy-mcp-postgres`, extra `easy-mcp-kit[postgres]`): schema and
+    table discovery plus `query`, every statement in a `READ ONLY` transaction with
+    a statement timeout and a row cap; `DATABASE_URL` read from the environment.
+
+### Fixed
+
+- `mypy` passes again (`build_tool` typed the tool name loosely) and now runs in CI,
+  so type regressions cannot ship unnoticed.
+- The sliding-window rate limiter forgets clients whose history has aged out of the
+  window, so a long-running public server no longer grows memory with every distinct
+  client it has ever seen.
+- Opening a legacy SSE session (`GET /sse`) now spends the client's rate-limit budget
+  and answers `429` with `Retry-After` when it is exhausted. Previously an anonymous
+  client could fill `max_sessions` and lock everyone else out with `503`s.
+
+### Changed
+
+- API keys are compared as SHA-256 digests, so the constant-time check no longer
+  reveals a key's length either.
+- Following JSON Schema, a number with no fractional part (`3.0`) is accepted for an
+  `int` parameter and reaches the tool as `int`. `validate_arguments` now returns the
+  normalized arguments instead of `None`.
+- The package version lives in one place (`easy_mcp/_version.py`); `pyproject.toml`
+  reads it at build time and `MCPServer` reports it by default.
+- `MCPServer.check_rate_limit()` is public so custom transports can charge the
+  budget for work that happens before a message exists.
+- Transports are typed against `MCPServer` instead of `Any`.
+- CI tests Python 3.14 and uses the current `actions/checkout` and
+  `actions/setup-python` releases.
+
+## [0.2.2] - 2026-09-10
+
+- Refreshed the demo video and code snapshots in `docs/`.
+- Documentation describes MCP clients generically.
+
+## [0.2.1] - 2026-09-10
+
+### Added
+
+- Streamable HTTP transport, the MCP spec's current HTTP transport: one `/mcp`
+  endpoint with `MCP-Session-Id` sessions, `DELETE` to end a session, idle-session
+  expiry, and an `Origin` allowlist (`allowed_origins`) against DNS rebinding.
+  `server.run()` now serves it by default with the legacy `/sse` + `/messages`
+  endpoints alongside.
+- Protocol version negotiation for `2024-11-05` through `2025-11-25`, verified
+  against the official Python and TypeScript SDK clients.
+
+## [0.2.0] - 2026-09-03
+
+### Added
+
+- stdio transport (`server.run("stdio")`, `StdioTransport`) for desktop MCP hosts
+  and local agents, with `EASY_MCP_STDIO_API_KEY` for protected tools and
+  `sys.stdout` redirected to stderr while serving so stray prints cannot corrupt the
+  protocol stream.
+- Demo video, code snapshots, and status badges in the README.
+
+## [0.1.0] - 2026-08-30
+
+### Added
+
+- Initial release: `@server.tool` registration with JSON Schema generated from type
+  hints and docstrings, strict argument validation, `APIKeyAuth` with per-tool
+  scopes and hidden protected tools, sliding-window rate limiting, payload caps,
+  per-tool timeouts and per-session call caps, sanitized errors with `error_id`
+  correlation, structured JSON logs with an audit trail, and the HTTP + SSE
+  transport.
+
+[Unreleased]: https://github.com/Mark007-R/Easy-MCP/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/Mark007-R/Easy-MCP/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/Mark007-R/Easy-MCP/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/Mark007-R/Easy-MCP/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/Mark007-R/Easy-MCP/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Mark007-R/Easy-MCP/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Mark007-R/Easy-MCP/releases/tag/v0.1.0

{easy_mcp_kit-0.2.2 → easy_mcp_kit-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easy-mcp-kit
-Version: 0.2.2
+Version: 0.2.4
 Summary: Build secure MCP (Model Context Protocol) servers from plain Python functions.
 Project-URL: Homepage, https://github.com/Mark007-R/Easy-MCP
 Project-URL: Repository, https://github.com/Mark007-R/Easy-MCP
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -27,9 +28,14 @@ Requires-Dist: uvicorn>=0.30
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
 Description-Content-Type: text/markdown
 
 # easy_mcp
@@ -83,12 +89,15 @@ Requires Python 3.11+. Only two runtime dependencies: `starlette` and `uvicorn`.
 | Concern | What you write | What easy_mcp does |
 |---|---|---|
 | Schemas | Type hints | Generates strict JSON Schema (`additionalProperties: false`) |
-| Descriptions | Docstrings | Parses summary + Google-style `Args:` into tool/param descriptions |
+| Descriptions | Docstrings or `Annotated` | Parses summary + Google-style `Args:` into tool/param descriptions; `Annotated[int, "..."]` documents a parameter in place |
 | Validation | Nothing | Rejects unknown fields, wrong types, missing params — before your code runs |
+| Structured results | A return type | Publishes `outputSchema` and answers with `structuredContent` |
+| Rich schemas | A Pydantic model (optional) | The model's own schema and validation, for parameters and results |
 | Auth | `auth=APIKeyAuth({...})` | Constant-time key checks, per-tool scopes, hidden protected tools |
 | Rate limits | `rate_limit_per_minute=120` | Sliding-window limiter per client |
 | Errors | Just `raise` | Clients get a sanitized message + `error_id`; the log gets the traceback |
 | Crashes | Nothing | One failing tool never takes down the server |
+| Launching | Nothing | `easy-mcp run my_tools:server` serves a module on any transport |
 
 ## Quickstart tour
 
@@ -105,6 +114,14 @@ def word_count(text: str) -> dict[str, int]:
     """
     return {"words": len(text.split()), "characters": len(text)}
 
+# Or document a parameter where it is declared, instead of in the docstring.
+# Annotated is plain typing (from typing import Annotated) and the tool still
+# receives an int; where both exist, the annotation wins.
+@server.tool
+def tail_log(lines: Annotated[int, "How many lines to return, newest first"]) -> list[str]:
+    """Read the end of the log."""
+    ...
+
 # With options:
 @server.tool(name="summarize", tags=("stats",), category="math",
              examples=({"arguments": {"values": [1, 2, 3]}},), timeout=5.0)
@@ -137,6 +154,85 @@ server.unregister_tool("late_tool")
 Anything else is rejected **at registration time** with a clear error — never
 at call time. Validation is strict: booleans are not integers, unknown
 arguments are hard errors, and every violation is reported (not just the first).
+Following JSON Schema, a number with no fractional part (`3.0`) is a valid
+integer; it reaches your function as `int`, so `range(times)` never sees a float.
+
+### Structured results
+
+A tool whose return annotation describes a JSON object publishes an
+`outputSchema`, and its results carry `structuredContent` so clients get typed
+data instead of a string they have to parse:
+
+```python
+@server.tool
+def weather(city: str) -> dict[str, float]:
+    """Get current weather."""
+    return {"temperature": 22.5, "humidity": 65}
+```
+
+```jsonc
+// tools/call result
+{
+  "content": [{"type": "text", "text": "{\"humidity\": 65, \"temperature\": 22.5}"}],
+  "structuredContent": {"humidity": 65, "temperature": 22.5},
+  "isError": false
+}
+```
+
+The text block stays for clients that predate structured content — the spec
+asks for both, and they always hold the same data.
+
+MCP carries structured content as a JSON *object*, so only object-shaped
+returns get a schema; `-> str` and `-> list[int]` tools are unchanged. A
+missing or unsupported return annotation is not an error, it just means no
+schema. Pass `output_schema={...}` to declare one yourself, or
+`output_schema={}` to advertise none.
+
+Because the schema is a promise to clients, results are checked against it
+before they are sent. A tool that breaks its own contract fails the call with
+an `error_id` rather than shipping data that does not match.
+
+### Pydantic models (optional)
+
+For a parameter too complex for a plain type hint, annotate it with a Pydantic
+v2 model. Install it with `pip install "easy-mcp-kit[pydantic]"`; easy_mcp
+never imports Pydantic itself, so projects that skip it pay nothing.
+
+```python
+class Address(BaseModel):
+    city: str
+    zip_code: str | None = None
+
+class User(BaseModel):
+    name: str = Field(min_length=1)
+    age: int
+    home: Address
+
+@server.tool
+def save_user(user: User) -> Saved:
+    """Save a user.
+
+    Args:
+        user: The person to store.
+    """
+    return Saved(id=7, label=user.name)
+```
+
+Clients receive the model's own JSON Schema — constraints like `minLength`
+included — and the tool receives a validated `User` instance, not a dict. A
+model return type becomes the `outputSchema`, and the tool may return either an
+instance or any dict the model accepts.
+
+Pydantic does the validating inside a model rather than the built-in validator,
+so you get every error it finds instead of the first one a weaker second copy
+of its rules would hit. The outer guarantees are unchanged: unknown top-level
+arguments are still a hard error.
+
+Two limits worth knowing. A model must be a whole parameter or return type —
+`list[User]` is refused at registration, because a model brings `$defs` and
+hoisting those out of an arbitrary nesting depth is ambiguous; wrap it in a
+model instead. And two different models that share a class name in one tool are
+refused for the same reason: their definitions would collide.
 
 ### Transports: Streamable HTTP, SSE, or stdio
 
@@ -197,6 +293,28 @@ Authentication works the same way as over SSE, except the credential is the
 `StdioTransport(server, api_key=...)`) instead of a header. An invalid key
 fails at startup rather than silently downgrading to anonymous access.
 
+### Launching from the command line
+
+A module of `@server.tool` functions does not need a `__main__` block to be
+runnable:
+
+```bash
+easy-mcp run my_tools:server              # Streamable HTTP on the server's own host/port
+easy-mcp run my_tools --transport stdio   # attribute defaults to "server"
+easy-mcp run my_tools:server --host 0.0.0.0 --port 9000
+```
+
+The target is `module:attribute`, resolved from the current directory;
+`my_tools.py:server` works too. The attribute may be a server or a callable
+returning one, so a factory that reads configuration at startup is fine.
+
+`--host`, `--port` and `--debug` override the server's own constructor
+arguments, and only when given — the transport is the one thing you usually
+want to vary per host, since a desktop MCP client wants `stdio` where
+everything else wants HTTP.
+
+Importing a module runs it, so point this only at code you trust.
+
 ### Authentication and per-tool permissions
 
 ```python
@@ -301,6 +419,50 @@ asyncio.run(main())
 Stdio servers are started by the MCP host itself, from a config entry like the
 one in [Transports](#transports-streamable-http-sse-or-stdio).
 
+## Ready-made connectors
+
+Two servers ship with the package. They are built on the same `@server.tool`
+decorator you use, so everything above (validation, scopes, rate limits,
+timeouts, sanitized errors, audit log) applies to them unchanged.
+
+| Connector | Command | Credential | Tools |
+|---|---|---|---|
+| GitHub | `easy-mcp-github` | `GITHUB_TOKEN` (optional; public data without it) | `list_repos`, `get_repo`, `list_issues`, `get_issue`, `list_pull_requests`, `get_pull_request`, `get_file`, and with `--allow-write`: `create_issue`, `comment_on_issue` |
+| Postgres | `easy-mcp-postgres` | `DATABASE_URL` | `list_schemas`, `list_tables`, `describe_table`, `query` |
+
+```bash
+pip install "easy-mcp-kit[postgres]"   # the GitHub connector needs no extra
+
+GITHUB_TOKEN=github_pat_... easy-mcp-github --transport stdio
+DATABASE_URL=postgresql://user:pass@host/db easy-mcp-postgres --port 8011
+```
+
+Both take `--transport {http,sse,stdio}`, `--host`, `--port`, `--rate-limit`
+and `--debug`, and load API keys from `EASY_MCP_API_KEYS` when it is set.
+`python -m easy_mcp.connectors.github` and `... .postgres` work as well, and
+each module's `build_server(...)` returns a normal `MCPServer` for embedding.
+
+**GitHub** is read-only by default. `--allow-write` registers `create_issue`
+and `comment_on_issue`, which are gated by the `github:write` scope: only a
+client presenting a key that holds it can see or call them, and starting
+with `--allow-write` but no keys is refused. The token is sent only to
+`GITHUB_API_URL` (default `https://api.github.com`) and never appears in logs
+or errors. Use a fine-grained token scoped to the repositories you need.
+
+```bash
+export EASY_MCP_API_KEYS="a-long-random-key:github:write"   # key : scope
+easy-mcp-github --allow-write --transport stdio             # stdio: EASY_MCP_STDIO_API_KEY=a-long-random-key
+```
+
+**Postgres** runs every statement in a `READ ONLY` transaction
+(`default_transaction_read_only=on` is set for the session, so a query cannot
+turn it off) with a statement timeout (`--statement-timeout`, default 10 s)
+and a row cap (`--max-rows`, default 500; `query` returns `truncated: true`
+when it hit the cap). Writes are rejected by the database itself, not by
+parsing SQL. Still connect with a dedicated role holding only `SELECT`
+grants: a read-only transaction does not stop side-effecting functions that
+role is allowed to call.
+
 ## Architecture
 
 ```
@@ -317,6 +479,10 @@ easy_mcp/
 │   ├── streamable_http.py  Streamable HTTP transport (/mcp, sessions)
 │   ├── sse.py       legacy HTTP + SSE transport (Starlette/uvicorn)
 │   └── stdio.py     stdin/stdout transport (desktop MCP hosts, local agents)
+├── connectors/
+│   ├── _cli.py      shared --transport/--host/--port options
+│   ├── github.py    GitHub connector (stdlib HTTP; read-only unless --allow-write)
+│   └── postgres.py  Postgres connector (psycopg; READ ONLY, timeout, row cap)
 ├── protocol.py      supported MCP protocol versions + negotiation
 ├── exceptions.py    error hierarchy + stable JSON-RPC error codes
 └── logging.py       JSON logs + audit trail
@@ -353,10 +519,14 @@ prefer returning compact structures over huge strings.
 
 ```bash
 pip install -e .[dev]
-pytest            # 95+ tests: schema, dispatch, security, Streamable HTTP, SSE, stdio
+pytest            # 100+ tests: schema, dispatch, security, Streamable HTTP, SSE, stdio
 ruff check .
+mypy easy_mcp
 ```
 
+CI runs the same three commands on Python 3.11 through 3.14. Releases are
+listed in [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

{easy_mcp_kit-0.2.2 → easy_mcp_kit-0.2.4}/README.md

@@ -49,12 +49,15 @@ Requires Python 3.11+. Only two runtime dependencies: `starlette` and `uvicorn`.
 | Concern | What you write | What easy_mcp does |
 |---|---|---|
 | Schemas | Type hints | Generates strict JSON Schema (`additionalProperties: false`) |
-| Descriptions | Docstrings | Parses summary + Google-style `Args:` into tool/param descriptions |
+| Descriptions | Docstrings or `Annotated` | Parses summary + Google-style `Args:` into tool/param descriptions; `Annotated[int, "..."]` documents a parameter in place |
 | Validation | Nothing | Rejects unknown fields, wrong types, missing params — before your code runs |
+| Structured results | A return type | Publishes `outputSchema` and answers with `structuredContent` |
+| Rich schemas | A Pydantic model (optional) | The model's own schema and validation, for parameters and results |
 | Auth | `auth=APIKeyAuth({...})` | Constant-time key checks, per-tool scopes, hidden protected tools |
 | Rate limits | `rate_limit_per_minute=120` | Sliding-window limiter per client |
 | Errors | Just `raise` | Clients get a sanitized message + `error_id`; the log gets the traceback |
 | Crashes | Nothing | One failing tool never takes down the server |
+| Launching | Nothing | `easy-mcp run my_tools:server` serves a module on any transport |
 
 ## Quickstart tour
 
@@ -71,6 +74,14 @@ def word_count(text: str) -> dict[str, int]:
     """
     return {"words": len(text.split()), "characters": len(text)}
 
+# Or document a parameter where it is declared, instead of in the docstring.
+# Annotated is plain typing (from typing import Annotated) and the tool still
+# receives an int; where both exist, the annotation wins.
+@server.tool
+def tail_log(lines: Annotated[int, "How many lines to return, newest first"]) -> list[str]:
+    """Read the end of the log."""
+    ...
+
 # With options:
 @server.tool(name="summarize", tags=("stats",), category="math",
              examples=({"arguments": {"values": [1, 2, 3]}},), timeout=5.0)
@@ -103,6 +114,85 @@ server.unregister_tool("late_tool")
 Anything else is rejected **at registration time** with a clear error — never
 at call time. Validation is strict: booleans are not integers, unknown
 arguments are hard errors, and every violation is reported (not just the first).
+Following JSON Schema, a number with no fractional part (`3.0`) is a valid
+integer; it reaches your function as `int`, so `range(times)` never sees a float.
+
+### Structured results
+
+A tool whose return annotation describes a JSON object publishes an
+`outputSchema`, and its results carry `structuredContent` so clients get typed
+data instead of a string they have to parse:
+
+```python
+@server.tool
+def weather(city: str) -> dict[str, float]:
+    """Get current weather."""
+    return {"temperature": 22.5, "humidity": 65}
+```
+
+```jsonc
+// tools/call result
+{
+  "content": [{"type": "text", "text": "{\"humidity\": 65, \"temperature\": 22.5}"}],
+  "structuredContent": {"humidity": 65, "temperature": 22.5},
+  "isError": false
+}
+```
+
+The text block stays for clients that predate structured content — the spec
+asks for both, and they always hold the same data.
+
+MCP carries structured content as a JSON *object*, so only object-shaped
+returns get a schema; `-> str` and `-> list[int]` tools are unchanged. A
+missing or unsupported return annotation is not an error, it just means no
+schema. Pass `output_schema={...}` to declare one yourself, or
+`output_schema={}` to advertise none.
+
+Because the schema is a promise to clients, results are checked against it
+before they are sent. A tool that breaks its own contract fails the call with
+an `error_id` rather than shipping data that does not match.
+
+### Pydantic models (optional)
+
+For a parameter too complex for a plain type hint, annotate it with a Pydantic
+v2 model. Install it with `pip install "easy-mcp-kit[pydantic]"`; easy_mcp
+never imports Pydantic itself, so projects that skip it pay nothing.
+
+```python
+class Address(BaseModel):
+    city: str
+    zip_code: str | None = None
+
+class User(BaseModel):
+    name: str = Field(min_length=1)
+    age: int
+    home: Address
+
+@server.tool
+def save_user(user: User) -> Saved:
+    """Save a user.
+
+    Args:
+        user: The person to store.
+    """
+    return Saved(id=7, label=user.name)
+```
+
+Clients receive the model's own JSON Schema — constraints like `minLength`
+included — and the tool receives a validated `User` instance, not a dict. A
+model return type becomes the `outputSchema`, and the tool may return either an
+instance or any dict the model accepts.
+
+Pydantic does the validating inside a model rather than the built-in validator,
+so you get every error it finds instead of the first one a weaker second copy
+of its rules would hit. The outer guarantees are unchanged: unknown top-level
+arguments are still a hard error.
+
+Two limits worth knowing. A model must be a whole parameter or return type —
+`list[User]` is refused at registration, because a model brings `$defs` and
+hoisting those out of an arbitrary nesting depth is ambiguous; wrap it in a
+model instead. And two different models that share a class name in one tool are
+refused for the same reason: their definitions would collide.
 
 ### Transports: Streamable HTTP, SSE, or stdio
 
@@ -163,6 +253,28 @@ Authentication works the same way as over SSE, except the credential is the
 `StdioTransport(server, api_key=...)`) instead of a header. An invalid key
 fails at startup rather than silently downgrading to anonymous access.
 
+### Launching from the command line
+
+A module of `@server.tool` functions does not need a `__main__` block to be
+runnable:
+
+```bash
+easy-mcp run my_tools:server              # Streamable HTTP on the server's own host/port
+easy-mcp run my_tools --transport stdio   # attribute defaults to "server"
+easy-mcp run my_tools:server --host 0.0.0.0 --port 9000
+```
+
+The target is `module:attribute`, resolved from the current directory;
+`my_tools.py:server` works too. The attribute may be a server or a callable
+returning one, so a factory that reads configuration at startup is fine.
+
+`--host`, `--port` and `--debug` override the server's own constructor
+arguments, and only when given — the transport is the one thing you usually
+want to vary per host, since a desktop MCP client wants `stdio` where
+everything else wants HTTP.
+
+Importing a module runs it, so point this only at code you trust.
+
 ### Authentication and per-tool permissions
 
 ```python
@@ -267,6 +379,50 @@ asyncio.run(main())
 Stdio servers are started by the MCP host itself, from a config entry like the
 one in [Transports](#transports-streamable-http-sse-or-stdio).
 
+## Ready-made connectors
+
+Two servers ship with the package. They are built on the same `@server.tool`
+decorator you use, so everything above (validation, scopes, rate limits,
+timeouts, sanitized errors, audit log) applies to them unchanged.
+
+| Connector | Command | Credential | Tools |
+|---|---|---|---|
+| GitHub | `easy-mcp-github` | `GITHUB_TOKEN` (optional; public data without it) | `list_repos`, `get_repo`, `list_issues`, `get_issue`, `list_pull_requests`, `get_pull_request`, `get_file`, and with `--allow-write`: `create_issue`, `comment_on_issue` |
+| Postgres | `easy-mcp-postgres` | `DATABASE_URL` | `list_schemas`, `list_tables`, `describe_table`, `query` |
+
+```bash
+pip install "easy-mcp-kit[postgres]"   # the GitHub connector needs no extra
+
+GITHUB_TOKEN=github_pat_... easy-mcp-github --transport stdio
+DATABASE_URL=postgresql://user:pass@host/db easy-mcp-postgres --port 8011
+```
+
+Both take `--transport {http,sse,stdio}`, `--host`, `--port`, `--rate-limit`
+and `--debug`, and load API keys from `EASY_MCP_API_KEYS` when it is set.
+`python -m easy_mcp.connectors.github` and `... .postgres` work as well, and
+each module's `build_server(...)` returns a normal `MCPServer` for embedding.
+
+**GitHub** is read-only by default. `--allow-write` registers `create_issue`
+and `comment_on_issue`, which are gated by the `github:write` scope: only a
+client presenting a key that holds it can see or call them, and starting
+with `--allow-write` but no keys is refused. The token is sent only to
+`GITHUB_API_URL` (default `https://api.github.com`) and never appears in logs
+or errors. Use a fine-grained token scoped to the repositories you need.
+
+```bash
+export EASY_MCP_API_KEYS="a-long-random-key:github:write"   # key : scope
+easy-mcp-github --allow-write --transport stdio             # stdio: EASY_MCP_STDIO_API_KEY=a-long-random-key
+```
+
+**Postgres** runs every statement in a `READ ONLY` transaction
+(`default_transaction_read_only=on` is set for the session, so a query cannot
+turn it off) with a statement timeout (`--statement-timeout`, default 10 s)
+and a row cap (`--max-rows`, default 500; `query` returns `truncated: true`
+when it hit the cap). Writes are rejected by the database itself, not by
+parsing SQL. Still connect with a dedicated role holding only `SELECT`
+grants: a read-only transaction does not stop side-effecting functions that
+role is allowed to call.
+
 ## Architecture
 
 ```
@@ -283,6 +439,10 @@ easy_mcp/
 │   ├── streamable_http.py  Streamable HTTP transport (/mcp, sessions)
 │   ├── sse.py       legacy HTTP + SSE transport (Starlette/uvicorn)
 │   └── stdio.py     stdin/stdout transport (desktop MCP hosts, local agents)
+├── connectors/
+│   ├── _cli.py      shared --transport/--host/--port options
+│   ├── github.py    GitHub connector (stdlib HTTP; read-only unless --allow-write)
+│   └── postgres.py  Postgres connector (psycopg; READ ONLY, timeout, row cap)
 ├── protocol.py      supported MCP protocol versions + negotiation
 ├── exceptions.py    error hierarchy + stable JSON-RPC error codes
 └── logging.py       JSON logs + audit trail
@@ -319,10 +479,14 @@ prefer returning compact structures over huge strings.
 
 ```bash
 pip install -e .[dev]
-pytest            # 95+ tests: schema, dispatch, security, Streamable HTTP, SSE, stdio
+pytest            # 100+ tests: schema, dispatch, security, Streamable HTTP, SSE, stdio
 ruff check .
+mypy easy_mcp
 ```
 
+CI runs the same three commands on Python 3.11 through 3.14. Releases are
+listed in [CHANGELOG.md](CHANGELOG.md).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).