From 84411a16d9fd6054a916bc5298f774612a55938f Mon Sep 17 00:00:00 2001 From: Phil Date: Wed, 11 Nov 2026 16:36:58 -0700 Subject: [PATCH] feat: MCP server for AI clients (v2.15.0, ADR-075) Add an MCP server at SITE_URL/mcp so AI assistants (claude.ai connectors, Claude Code) can search, read and write notes. - starpunk/mcp_server: official MCP SDK 2.3, stateless Streamable HTTP with JSON responses, served by uvicorn as a sidecar from the same image. Ten tools; writes go through the Micropub handlers. - IndieAuth: RFC 8707 resource indicators bound to codes and tokens (migration 022), client ID metadata document + public client metadata, draft in scopes_supported, default MCP scopes, consent screen note. - BACKGROUND_WORKERS_ENABLED flag so the sidecar runs no workers. - Docs: ADR-075, architecture/mcp.md and updates; CHANGELOG. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 15 + Containerfile | 2 + README.md | 3 + docs/architecture/INDEX.md | 3 +- docs/architecture/database.md | 9 +- docs/architecture/deployment.md | 9 + docs/architecture/mcp.md | 77 ++++ docs/architecture/overview.md | 12 +- .../simplified-auth-architecture.md | 28 +- docs/architecture/technology-stack.md | 3 + docs/decisions/ADR-075-mcp-server.md | 121 ++++++ docs/decisions/INDEX.md | 7 +- migrations/022_indieauth_resource.sql | 6 + requirements.txt | 6 +- starpunk/__init__.py | 13 +- starpunk/config.py | 2 + starpunk/indieauth.py | 74 +++- starpunk/mcp_server/__init__.py | 13 + starpunk/mcp_server/app.py | 13 + starpunk/mcp_server/auth.py | 56 +++ starpunk/mcp_server/server.py | 95 +++++ starpunk/mcp_server/tools.py | 362 ++++++++++++++++++ starpunk/routes/indieauth.py | 16 +- templates/admin/authorize.html | 5 + templates/admin/tokens.html | 4 +- tests/test_indieauth.py | 80 +++- tests/test_mcp.py | 259 +++++++++++++ 27 files changed, 1248 insertions(+), 45 deletions(-) create mode 100644 docs/architecture/mcp.md create mode 100644 docs/decisions/ADR-075-mcp-server.md create mode 100644 migrations/022_indieauth_resource.sql create mode 100644 starpunk/mcp_server/__init__.py create mode 100644 starpunk/mcp_server/app.py create mode 100644 starpunk/mcp_server/auth.py create mode 100644 starpunk/mcp_server/server.py create mode 100644 starpunk/mcp_server/tools.py create mode 100644 tests/test_mcp.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c05e2d..eaf7b46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.15.0] - 2026-11-11 + +MCP server for AI clients (ADR-075). + +### Added + +- An [MCP](https://modelcontextprotocol.io/) server at `SITE_URL/mcp`. AI assistants such as claude.ai custom connectors and Claude Code can search, list and read notes and drafts, list tags, create notes (drafts by default), update, delete and undelete them, and upload photos. Writes go through the Micropub handlers, so scopes, crossposting, webmentions and WebSub behave the same as with any Micropub app +- The MCP server runs as a sidecar from the same image (`uvicorn starpunk.mcp_server.app:app --port 8001`) with `BACKGROUND_WORKERS_ENABLED=false`; the proxy sends `/mcp*` and `/.well-known/oauth-protected-resource*` to it. New dependencies: `mcp` 2.3 and `uvicorn` 0.54 +- The IndieAuth server accepts RFC 8707 `resource` for the MCP endpoint and binds codes and tokens to it (migration 022). Its metadata advertises client ID metadata documents and public clients (`token_endpoint_auth_methods_supported: ["none"]`), so Claude connects without dynamic client registration. The consent screen says when an AI assistant is asking, and Connected Apps marks MCP tokens +- `BACKGROUND_WORKERS_ENABLED` (default `true`) turns off the webmention, WebSub and syndication workers + +### Fixed + +- `scopes_supported` in the IndieAuth metadata lists `draft`, which Micropub already honoured + ## [2.14.2] - 2026-11-10 ### Added diff --git a/Containerfile b/Containerfile index 64787e6..0643517 100644 --- a/Containerfile +++ b/Containerfile @@ -78,6 +78,8 @@ USER starpunk # Expose application port EXPOSE 8000 +# MCP sidecar (same image, run with: uvicorn starpunk.mcp_server.app:app --host 0.0.0.0 --port 8001) +EXPOSE 8001 # Health check # Uses httpx (already in requirements) to verify app is responding diff --git a/README.md b/README.md index e20cbf1..14c6223 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,9 @@ what changed in each release is in [CHANGELOG.md](CHANGELOG.md). - Built-in [IndieAuth](https://indieauth.spec.indieweb.org/) server for Micropub apps (consent screen, tokens, revocation, Connected Apps page) - Admin login through any OpenID Connect provider (e.g. Pocket ID) +- [MCP](https://modelcontextprotocol.io/) server at `/mcp` so AI assistants + (claude.ai connectors, Claude Code…) can search, read and write notes + after you approve them, run as an optional sidecar (ADR-075) - [Webmention](https://www.w3.org/TR/webmention/): receiving (verified, moderated, rate-limited) and sending; replies, quotes and mentions shown on each note, with likes, reposts and replies as a line of counts with diff --git a/docs/architecture/INDEX.md b/docs/architecture/INDEX.md index 1c89488..efc3e35 100644 --- a/docs/architecture/INDEX.md +++ b/docs/architecture/INDEX.md @@ -13,10 +13,11 @@ original v0.x technology choices are kept in |----------|-------------| | [overview.md](overview.md) | System overview: purpose, request flow, modules and routes, background workers, storage, auth model, URL surface, caching, security posture | | [technology-stack.md](technology-stack.md) | Current runtime, Python dependencies, standards implemented, testing and CI | -| [database.md](database.md) | SQLite schema after migrations 001–021, migration runner and its lock, connection pool | +| [database.md](database.md) | SQLite schema after migrations 001–022, migration runner and its lock, connection pool | | [deployment.md](deployment.md) | Container image stages, CI workflow, release process, `/data` layout, reverse proxy, all environment variables | | [simplified-auth-architecture.md](simplified-auth-architecture.md) | Admin login via OpenID Connect and the built-in IndieAuth server that issues Micropub tokens (ADR-064) | | [indieweb-protocols.md](indieweb-protocols.md) | How Micropub, IndieAuth, Webmention, microformats2, WebSub and the feeds are implemented (including backfeed responses, web actions and notifications), with compliance status and known gaps | +| [mcp.md](mcp.md) | The MCP server for AI clients: sidecar, authorization flow, tools (ADR-075) | | [syndication-architecture.md](syndication-architecture.md) | Crossposting (POSSE) to GoToSocial, Bluesky and Threads: syndications table, worker, reconcile rules, backfeed of responses (ADR-073) | ## Where to start diff --git a/docs/architecture/database.md b/docs/architecture/database.md index 5b3ca5e..864492a 100644 --- a/docs/architecture/database.md +++ b/docs/architecture/database.md @@ -2,7 +2,7 @@ **Version**: 2.14.0 (2026-11-10) **Status**: Current. Verified against a database created by `create_app()` -with migrations 001–021. +with migrations 001–022. StarPunk uses one SQLite file, `starpunk.db` under `DATA_PATH` (`/data` in the container), in WAL mode. Note *content* is not in the database: it lives @@ -75,6 +75,7 @@ Background: [ADR-031](../decisions/ADR-031-database-migration-system-redesign.md | `019_shared_rate_limits.sql` | 2.11.0 | `rate_limits` (counters shared by all processes) | | `020_backfeed.sql` | 2.13.0 | Rebuilds `webmentions` adding `origin`, `remote_id`, the `quote` type and an index on (`target_note_id`, `origin`); `syndications.backfeed_next_at`, `backfeed_checked_at`, `backfeed_claimed_until`, `backfeed_attempts`, `backfeed_error`, `backfeed_backfill`, `likes_count`, `reposts_count`, `quotes_count` | | `021_notifications.sql` | 2.14.0 | `webmentions.notified_at`; existing rows are marked as notified | +| `022_indieauth_resource.sql` | 2.15.0 | `indieauth_codes.resource` and `indieauth_tokens.resource` (RFC 8707, MCP tokens; ADR-075) | New migrations are numbered `NNN_description.sql`, must be safe to run inside one transaction, and should use `IF NOT EXISTS` where SQLite allows it. @@ -128,12 +129,12 @@ value), `me`, `created_at`, `expires_at`, `last_used_at`, `user_agent`, (primary key), `nonce`, `code_verifier` (PKCE), `next_url`, `expires_at`. Consumed once on callback. -**`indieauth_codes`**: authorization codes issued to Micropub clients: +**`indieauth_codes`**: authorization codes issued to Micropub and MCP clients: `code_hash`, `client_id`, `redirect_uri`, `scope`, `code_challenge`, -`expires_at`, `used_at` (single use). +`resource` (`SITE_URL/mcp` or NULL), `expires_at`, `used_at` (single use). **`indieauth_tokens`**: access tokens: `token_hash`, `client_id`, `scope`, -`created_at`, `expires_at`, `last_used_at`, `revoked_at`. Listed and revoked +`resource` (`SITE_URL/mcp` for MCP tokens, NULL for Micropub), `created_at`, `expires_at`, `last_used_at`, `revoked_at`. Listed and revoked in `/admin/tokens`. **Legacy tables, unused**: `auth_state` (v1 IndieLogin login state), `tokens` diff --git a/docs/architecture/deployment.md b/docs/architecture/deployment.md index eb5f147..63f1ee0 100644 --- a/docs/architecture/deployment.md +++ b/docs/architecture/deployment.md @@ -125,6 +125,14 @@ WebSub rate limits need; without it, every client appears as the proxy's address and shares one limit. Do not set it if the container port can be reached without the proxy, because the header could then be forged. +The MCP sidecar (v2.15.0, ADR-075) is a second container from the same +image, with the same environment and `/data` volume plus +`BACKGROUND_WORKERS_ENABLED=false`, running +`uvicorn starpunk.mcp_server.app:app --host 0.0.0.0 --port 8001`. The proxy +sends `/mcp*` and `/.well-known/oauth-protected-resource*` to it, keeping the +`Host` header; everything else goes to port 8000. Without the sidecar the +site simply has no MCP endpoint. See [mcp.md](mcp.md). + `SITE_URL` must be the public `https://` URL: it is used for absolute links, feed and WebSub topic URLs, the IndieAuth issuer and redirect URIs, and to decide whether the session cookie is `Secure`. @@ -175,6 +183,7 @@ ignored with a warning. | `FLASK_DEBUG` | `0` | Debug off unless `1` (`flask run --debug` sets it locally); the image sets `0` | | `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | | `VERSION` | package `__version__` | Overrides the reported version; normally unset | +| `BACKGROUND_WORKERS_ENABLED` | `true` | `false` stops the webmention, WebSub and syndication workers; set in the MCP sidecar (v2.15.0) | ### Feeds diff --git a/docs/architecture/mcp.md b/docs/architecture/mcp.md new file mode 100644 index 0000000..277185f --- /dev/null +++ b/docs/architecture/mcp.md @@ -0,0 +1,77 @@ +# MCP server (v2.15.0) + +How AI clients use StarPunk through the +[Model Context Protocol](https://modelcontextprotocol.io/). The decision and +alternatives are in [ADR-075](../decisions/ADR-075-mcp-server.md). + +## Shape + +``` +client ──HTTPS──> reverse proxy + /mcp*, /.well-known/oauth-protected-resource* ──> starpunk-mcp:8001 (uvicorn, MCP SDK) + everything else (incl. /auth/*, /.well-known/oauth-authorization-server) + ──> starpunk:8000 (gunicorn, Flask) +starpunk and starpunk-mcp: same image, same environment, same /data volume +``` + +| Module | Role | +|---|---| +| `starpunk/mcp_server/app.py` | ASGI entry: `uvicorn starpunk.mcp_server.app:app --host 0.0.0.0 --port 8001` | +| `starpunk/mcp_server/server.py` | `create_mcp_server(app)` and `create_asgi_app(app=None)`: stateless Streamable HTTP, JSON responses, 16 MB request limit, DNS rebinding protection | +| `starpunk/mcp_server/auth.py` | `StarPunkTokenVerifier`: StarPunk tokens to SDK `AccessToken`s | +| `starpunk/mcp_server/tools.py` | The tools; each runs in a thread inside `app.test_request_context(base_url=SITE_URL)` | + +`create_asgi_app()` with no argument builds the Flask app from the +environment with `BACKGROUND_WORKERS_ENABLED=false`. The sidecar container +should also set that variable, for clarity. + +## Authorization flow + +1. The client POSTs to `/mcp` without a token and gets `401` with + `WWW-Authenticate: Bearer ... resource_metadata="SITE_URL/.well-known/oauth-protected-resource/mcp"`. +2. That document names `SITE_URL/mcp` as the resource and `SITE_URL/` as + the authorization server. The client reads + `/.well-known/oauth-authorization-server`, which says it accepts client ID + metadata documents and public clients. +3. The client sends the owner to `/auth/authorize` with its `client_id` URL, + PKCE and `resource=SITE_URL/mcp`. StarPunk fetches the client's metadata + document to check `redirect_uri` (unless it has the same origin as the + `client_id`), and the owner logs in with OIDC and approves. With no + `scope`, the default MCP scopes are offered. +4. The token endpoint exchanges the code. The token is bound to the + resource. +5. Each MCP request carries the token. The verifier looks it up and the SDK + refuses it unless its resource is `SITE_URL/mcp`. + +Details of codes, tokens and scopes are in +[simplified-auth-architecture.md](simplified-auth-architecture.md). + +## Tools + +| Tool | Does | Scope | +|---|---|---| +| `search_notes(query, include_drafts, limit)` | FTS5 search, with snippets | any; drafts need a posting scope | +| `list_notes(include_drafts, limit, offset)` | Newest first, summaries | any; drafts need a posting scope | +| `get_note(url_or_slug)` | Microformats2 properties (as Micropub `q=source`) | any; drafts need a posting scope | +| `list_tags(filter)` | Tags in use, most used first | posting scope | +| `get_site_config()` | Micropub `q=config`, including `syndicate-to` targets | any | +| `create_note(content, title, tags, draft=True, photos, in_reply_to, like_of, repost_of, bookmark_of, syndicate_to, slug, published_at)` | Micropub create | `create` or `draft` | +| `update_note(url, content, title, tags, add_tags, remove_tags, draft, photos, in_reply_to)` | Micropub update | `update` | +| `delete_note(url)`, `undelete_note(url)` | Soft delete and restore | `delete` | +| `upload_media(filename, data_base64)` | Save an image, return its URL | `media` or `create` | + +"Posting scope" means `create`, `update`, `delete` or `draft`. Limits are +capped at 100. Micropub errors come back as tool errors (`isError`) with the +Micropub error description. + +## Operating it + +- Environment: the same as the main container, plus + `BACKGROUND_WORKERS_ENABLED=false`. +- Proxy: route `/mcp*` and `/.well-known/oauth-protected-resource*` to port + 8001, keeping the `Host` header (DNS rebinding protection checks it + against `SITE_URL`). +- Connecting: claude.ai Settings → Connectors → Add custom connector with + `SITE_URL/mcp`; Claude Code: `claude mcp add --transport http starpunk + SITE_URL/mcp`, then `/mcp` to authenticate. +- Revoking: Admin → Connected Apps (MCP tokens are marked "(MCP)"). diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index cfaa750..a9bb185 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -223,6 +223,9 @@ coordinated through the data volume: | WebSub worker (`websub_worker.py`) | `WEBSUB_ENABLED` and not testing | Same pattern with `websub-worker.lock` | Verifies subscription intents, delivers topic content (signed with `X-Hub-Signature` when the subscriber gave a secret), retries, expires leases; pings an external hub instead if `WEBSUB_HUB_URL` is set | | Syndication worker (`syndication.py`) | At least one crosspost target configured, and not testing | No file lock. Rows in `syndications` are claimed with a 5-minute `claimed_until` lease by an atomic `UPDATE`, so any process may work a row but only one at a time; a `version` column keeps edits made during a send. Threads token refreshes are serialised with a lock file next to `threads_token.json`. | Creates, updates or deletes the remote post for each (note, target) pair; up to 8 attempts. Then, only when `BACKFEED_ENABLED`, backfeed: checks copies for responses, each claimed with a `backfeed_claimed_until` lease (v2.13.0, `backfeed.py`, ADR-073) | +`BACKGROUND_WORKERS_ENABLED=false` starts none of them; the MCP sidecar +(below) sets it so the workers only run in the main container. + All workers run inside an app context, are daemon threads (they end with the process) and sleep for their poll interval when there is nothing to do. Under the test suite (`TESTING=True`) none of them start; tests call the processing @@ -273,7 +276,14 @@ are in [simplified-auth-architecture.md](simplified-auth-architecture.md). OIDC) approves; the client exchanges the code at `/auth/token` (PKCE required). Codes and tokens are stored hashed. Tokens last `INDIEAUTH_TOKEN_LIFETIME_DAYS` and can be revoked at `/auth/revoke` or in - `/admin/tokens`. Scopes: `create`, `update`, `delete`, `media`, `profile`. + `/admin/tokens`. Scopes: `create`, `update`, `delete`, `media`, `draft`, + `profile`. +- **MCP (v2.15.0, ADR-075)**: AI clients use the same flow, identified by a + client ID metadata document and asking for `resource=SITE_URL/mcp`. Their + tokens are bound to that resource and checked by the MCP sidecar, a second + container (uvicorn, official MCP SDK) that the proxy sends `/mcp` to. Its + tools read, search and write notes through the Micropub handlers. See + [mcp.md](mcp.md). - **Development**: `DEV_MODE=true` adds `/dev/login`, which logs in as `DEV_ADMIN_ME` without any checks. Never enabled in production; start-up logs a warning when it is on. diff --git a/docs/architecture/simplified-auth-architecture.md b/docs/architecture/simplified-auth-architecture.md index d94822f..1e3fa1a 100644 --- a/docs/architecture/simplified-auth-architecture.md +++ b/docs/architecture/simplified-auth-architecture.md @@ -137,8 +137,10 @@ form `{"error", "error_description"}`. "token_endpoint": "/auth/token", "revocation_endpoint": "/auth/revoke", "revocation_endpoint_auth_methods_supported": ["none"], - "scopes_supported": ["create", "update", "delete", "media", "profile"], + "scopes_supported": ["create", "update", "delete", "media", "draft", "profile"], "response_types_supported": ["code"], + "token_endpoint_auth_methods_supported": ["none"], + "client_id_metadata_document_supported": true, "grant_types_supported": ["authorization_code"], "code_challenge_methods_supported": ["S256"], "authorization_response_iss_parameter_supported": true @@ -192,7 +194,7 @@ requested and left checked, issues a code, and redirects with `code`, | Value | 32 random bytes, URL-safe | 32 random bytes, URL-safe | | Stored as | SHA-256 hash | SHA-256 hash | | Lifetime | 10 minutes | `INDIEAUTH_TOKEN_LIFETIME_DAYS` (default 90) | -| Bound to | `client_id`, `redirect_uri`, `scope`, `code_challenge` | `client_id`, `scope` | +| Bound to | `client_id`, `redirect_uri`, `scope`, `code_challenge`, `resource` | `client_id`, `scope`, `resource` | `redeem_authorization_code` handles redemption for both `POST /auth/token` and `POST /auth/authorize`: @@ -213,11 +215,22 @@ refresh tokens: a client re-authorizes when its token expires. Expired codes are deleted whenever a new code is issued. +**Resource indicators (v2.15.0, ADR-075).** An authorization request may +include `resource` (RFC 8707). The only accepted value is `SITE_URL/mcp` +(a trailing slash is ignored); anything else is `invalid_target`. With it, +a request without `scope` is offered `create update delete media draft`, and +the consent screen says the client is an AI assistant using MCP. The resource +is stored on the code and then on the token. A token request that names a +different resource gets `invalid_target`. Micropub clients send no resource +and their tokens have none. The MCP endpoint only accepts tokens for its +resource; see [mcp.md](mcp.md). + ### Verification and revocation - `verify_access_token(token)` hashes the token and accepts it if it is neither revoked nor expired, then updates `last_used_at`. It returns - `{me: ADMIN_ME, client_id, scope}`. + `{me: ADMIN_ME, client_id, scope, resource, expires_at}`. The legacy + `GET /auth/token` still answers with only `me`, `client_id` and `scope`. - `check_scope(required, scope)` matches whole words in the space-separated scope string. - Revocation sets `revoked_at`. It can happen by token value, through @@ -308,8 +321,8 @@ enough. If it is another page, that page must advertise StarPunk's |---|---|---| | `sessions` | Admin browser sessions | `session_token_hash`, `me`, `expires_at`, `last_used_at`, `user_agent`, `ip_address` | | `oidc_login_state` | One pending OIDC login | `state` (PK), `nonce`, `code_verifier`, `next_url`, `expires_at` | -| `indieauth_codes` | Authorization codes | `code_hash`, `client_id`, `redirect_uri`, `scope`, `code_challenge`, `expires_at`, `used_at` | -| `indieauth_tokens` | Access tokens | `token_hash`, `client_id`, `scope`, `expires_at`, `last_used_at`, `revoked_at` | +| `indieauth_codes` | Authorization codes | `code_hash`, `client_id`, `redirect_uri`, `scope`, `code_challenge`, `resource` (migration 022), `expires_at`, `used_at` | +| `indieauth_tokens` | Access tokens | `token_hash`, `client_id`, `scope`, `resource` (migration 022), `expires_at`, `last_used_at`, `revoked_at` | The legacy v1 tables `auth_state`, `tokens` and `authorization_codes` are not used (see the migration's header comment). @@ -338,7 +351,6 @@ connection pinned, a 5-second limit). Known gaps: -- `scopes_supported` leaves out `draft`, although Micropub honours it and - the consent screen grants it when requested. Unknown scopes are also shown - and granted as requested; they just have no effect. +- Unknown scopes are shown and granted as requested; they just have no + effect. (`draft` has been listed in `scopes_supported` since v2.15.0.) - No token introspection endpoint and no refresh tokens. diff --git a/docs/architecture/technology-stack.md b/docs/architecture/technology-stack.md index 501817b..a8e791f 100644 --- a/docs/architecture/technology-stack.md +++ b/docs/architecture/technology-stack.md @@ -48,6 +48,8 @@ vulnerabilities (`pip-audit`); check again before each release. | python-dotenv | `1.2.*` | Loading `.env` | | Pillow | `13.0.*` | Image validation, resizing and variants; converting response avatars to 96 px WebP (`avatars.py`) | | pillow-heif | `1.8.*` | HEIC/HEIF uploads (iPhone photos) | +| mcp | `2.3.*` | MCP server for AI clients (`starpunk/mcp_server/`, ADR-075); brings Starlette, pydantic and anyio. Only the sidecar imports it | +| uvicorn | `0.54.*` | ASGI server for the MCP sidecar | `markupsafe` comes with Flask/Jinja2. @@ -72,6 +74,7 @@ front-end framework or bundler, no separate search server. | IndieWeb | Micropub (create, update, delete, undelete, queries, media endpoint), IndieAuth (authorization server with PKCE, metadata endpoint, token revocation), Webmention (send and receive), WebSub (publisher and built-in hub), microformats2 (h-entry, h-feed, h-card markup and parsing), rel=me, web actions (``), backfeed of responses from the silos | | Login | OpenID Connect authorization code flow with PKCE (provider: Pocket ID) | | Feeds | RSS 2.0, Atom 1.0, JSON Feed 1.1, OPML 2.0, HTTP content negotiation | +| AI clients | Model Context Protocol (Streamable HTTP, stateless), OAuth 2.0 Protected Resource Metadata (RFC 9728), Resource Indicators (RFC 8707), Client ID Metadata Documents | | Crossposting | Mastodon client API (GoToSocial), AT Protocol (Bluesky XRPC), Threads Graph API; the same APIs are read for backfeed | Protocol details: [indieweb-protocols.md](indieweb-protocols.md), diff --git a/docs/decisions/ADR-075-mcp-server.md b/docs/decisions/ADR-075-mcp-server.md new file mode 100644 index 0000000..a27b48a --- /dev/null +++ b/docs/decisions/ADR-075-mcp-server.md @@ -0,0 +1,121 @@ +# ADR-075: MCP server for AI clients + +## Status + +Accepted (v2.15.0, 2026-11-11) + +## Context + +The owner wants AI assistants (claude.ai custom connectors, Claude Code and +other [Model Context Protocol](https://modelcontextprotocol.io/) clients) to +read, search and write notes. Micropub already covers writing, but MCP +clients don't speak Micropub: they discover tools over MCP and get tokens +through OAuth 2.1 with protected resource metadata (RFC 9728), resource +indicators (RFC 8707), and either dynamic client registration or a Client ID +Metadata Document (CIMD). + +StarPunk already runs an OAuth/IndieAuth authorization server (ADR-064) with +PKCE, public clients only, and clients identified by a `client_id` URL whose +JSON document lists `redirect_uris`. That is what MCP calls CIMD. Claude uses +CIMD when the server's metadata says `client_id_metadata_document_supported: +true` and lists `none` in `token_endpoint_auth_methods_supported`. + +StarPunk is Flask on gunicorn sync workers (WSGI). The official MCP Python +SDK is ASGI. + +Options considered: + +1. **Local stdio bridge** that calls `/micropub` with a stored token, like + existing Micropub MCP servers. No server changes, but every client needs + the bridge installed, claude.ai and mobile can't use it, and reading is + limited to what Micropub queries expose. +2. **Hand-written MCP route in Flask**, stateless JSON only. No new + dependencies or processes, but StarPunk would own the protocol details + (version negotiation, JSON-RPC, Origin checks, auth metadata) and track + the spec itself. +3. **Official SDK in a sidecar process** from the same image, behind the + same reverse proxy, sharing the data volume. +4. **Dynamic client registration** (RFC 7591) in the authorization server. + Every connection would register a new client, and nothing needs it once + CIMD works. + +## Decision + +### 1. A sidecar running the official SDK (option 3) + +`starpunk/mcp_server/` builds an `mcp.server.MCPServer` (SDK 2.3) and serves +it with uvicorn (`uvicorn starpunk.mcp_server.app:app --port 8001`), as a +second container from the same image. The reverse proxy sends `/mcp*` and +`/.well-known/oauth-protected-resource*` to it and everything else to +gunicorn. The endpoint is `SITE_URL/mcp`. + +The transport is stateless Streamable HTTP with plain JSON responses. No +session lives in the process, so restarts and several workers are harmless. + +The sidecar builds the Flask app with `BACKGROUND_WORKERS_ENABLED=false`, so +only the main container runs the webmention, WebSub and syndication +workers. Each tool runs in a worker thread inside a Flask request context +for `SITE_URL`, and calls the same service functions as the web app. +SQLite (WAL) handles the second process like another gunicorn worker. + +### 2. StarPunk is the authorization server; the sidecar only checks tokens + +- The authorization server metadata adds + `client_id_metadata_document_supported: true` and + `token_endpoint_auth_methods_supported: ["none"]`, and `scopes_supported` + now includes `draft`. +- An authorization request may carry `resource` (RFC 8707). The only resource + StarPunk names is `SITE_URL/mcp`; anything else is `invalid_target`. The + resource is stored on the code and the token (migration 022), shown on the + consent screen, and must match if the token request repeats it. +- An MCP request with no `scope` is offered `create update delete media + draft`. The owner unticks what they don't want on the consent screen. + (The SDK publishes the resource's `scopes_supported` from its + required scopes, which StarPunk leaves empty so any token can connect.) +- The sidecar's `TokenVerifier` looks tokens up with `verify_access_token` + and reports their resource. With `validate_token_resource`, the SDK + refuses tokens not issued for `/mcp`, so a Micropub app's token can't be + replayed against MCP. MCP tokens still work at `/micropub`; both stay the + owner's own clients, and the Connected Apps page marks MCP tokens. +- DNS rebinding protection allows only the `SITE_URL` host and origin + (plus localhost in `DEV_MODE`). + +### 3. Tools: reading and writing notes, nothing else + +| Tool | Scope | +|---|---| +| `search_notes`, `list_notes`, `get_note`, `get_site_config` | any token; drafts need `create`, `update`, `delete` or `draft` | +| `list_tags` | `create`, `update`, `delete` or `draft` (as Micropub `q=category`) | +| `create_note` | `create` or `draft` (draft-only tokens always make drafts) | +| `update_note` | `update` | +| `delete_note`, `undelete_note` | `delete` | +| `upload_media` | `media` or `create` | + +Writing tools build a Micropub JSON request and call `handle_create`, +`handle_update` and `handle_delete`. Scope rules, validation, crossposting, +webmentions and WebSub notifications are therefore identical to Micropub. +`create_note` makes a draft unless told otherwise. Tool annotations mark +reading tools read-only and update and delete as destructive. + +Syndication management, webmention moderation and other admin functions are +not exposed. + +## Consequences + +- AI clients connect with just the URL: claude.ai via Settings → Connectors, + Claude Code via `claude mcp add --transport http starpunk SITE_URL/mcp`. + The owner approves them on the usual consent screen, and they appear (and + can be revoked) under Connected Apps. +- New runtime dependencies: `mcp` (with Starlette, pydantic and anyio) and + `uvicorn`. They are only imported by the sidecar. +- Deployments run a second container and need two proxy routes. A site that + doesn't run the sidecar just has no MCP; nothing else changes. +- There are still no refresh tokens. MCP clients re-authorize after + `INDIEAUTH_TOKEN_LIFETIME_DAYS`. +- SDK upgrades need care: 3.0 is expected to change defaults (for example + `validate_token_resource`, which StarPunk already sets). + +## Alternatives + +Options 1, 2 and 4 above. A stdio bridge could still be added later for +clients that can't do OAuth; it would use a token from this flow. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 68d86e9..1b20727 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -5,8 +5,8 @@ records one decision: its context, what was decided, and the consequences. Superseded ADRs are kept as history; their Status line names the ADR that replaced them. -**Total ADR files**: 70 (69 numbers: ADR-001 to ADR-044 and ADR-050 to -ADR-074, with two files numbered ADR-012). See [Numbering](#numbering). +**Total ADR files**: 71 (70 numbers: ADR-001 to ADR-044 and ADR-050 to +ADR-075, with two files numbered ADR-012). See [Numbering](#numbering). Status values: **Accepted** (in force), **Superseded** (replaced by a later ADR), **Deprecated** (withdrawn, nothing replaces it; none at present), @@ -95,6 +95,7 @@ See also [IndieWeb protocols](../architecture/indieweb-protocols.md). | [010](ADR-010-authentication-module-design.md) | Authentication Module Design | Accepted* | Single `auth.py` module and server-side sessions; the login flow is now ADR-064. | | [011](ADR-011-development-authentication-mechanism.md) | Development Authentication Mechanism | Accepted | `DEV_MODE` login bypass for local development only. | | [022](ADR-022-auth-route-prefix-fix.md) | Fix IndieAuth Callback Route Mismatch | Accepted | Auth routes live under `/auth` (v0.9.2). | +| [075](ADR-075-mcp-server.md) | MCP server for AI clients | Accepted | `/mcp` served by the official MCP SDK in a sidecar; StarPunk's IndieAuth server issues resource-bound tokens via client ID metadata documents (v2.15.0). | ### Operations, errors and monitoring @@ -169,7 +170,7 @@ was carried out and is not itself superseded. ## How to create a new ADR -1. Use the next number after the highest existing one (currently ADR-075). +1. Use the next number after the highest existing one (currently ADR-076). 2. Name it `ADR-NNN-brief-descriptive-title.md`. 3. Follow the format of recent ADRs (e.g. ADR-070, ADR-071): diff --git a/migrations/022_indieauth_resource.sql b/migrations/022_indieauth_resource.sql new file mode 100644 index 0000000..6ac7068 --- /dev/null +++ b/migrations/022_indieauth_resource.sql @@ -0,0 +1,6 @@ +-- Migration 022: RFC 8707 resource indicators for IndieAuth codes and tokens +-- Version: 2.15.0 (ADR-075) +-- Tokens for the MCP endpoint are bound to it; Micropub tokens leave it NULL. + +ALTER TABLE indieauth_codes ADD COLUMN resource TEXT; +ALTER TABLE indieauth_tokens ADD COLUMN resource TEXT; diff --git a/requirements.txt b/requirements.txt index 01c4747..ff60211 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -# StarPunk runtime dependencies (v2.11.0) +# StarPunk runtime dependencies (v2.15.0) # Pinned to a minor series; see docs/architecture/technology-stack.md. # Web framework and server @@ -25,3 +25,7 @@ apprise==2.2.* # Images Pillow==13.0.* pillow-heif==1.8.* + +# MCP server sidecar (v2.15.0, ADR-075): official SDK, served by uvicorn +mcp==2.3.* +uvicorn==0.54.* diff --git a/starpunk/__init__.py b/starpunk/__init__.py index 8a5582c..c24d3af 100644 --- a/starpunk/__init__.py +++ b/starpunk/__init__.py @@ -325,9 +325,12 @@ def create_app(config=None): register_error_handlers(app) + # Background workers, unless this process is the MCP sidecar (v2.15.0, ADR-075) + workers = app.config.get("BACKGROUND_WORKERS_ENABLED", True) + # Start webmention worker thread (v1.6.0 Phase 2) # Per background-worker.md: Skip in test mode - if app.config.get('WEBMENTION_WORKER_ENABLED', True) and not app.config.get('TESTING', False): + if workers and app.config.get('WEBMENTION_WORKER_ENABLED', True) and not app.config.get('TESTING', False): from starpunk.webmention_worker import WebmentionWorker webmention_worker = WebmentionWorker( app, @@ -348,13 +351,13 @@ def create_app(config=None): # Start WebSub worker (v2.10.0) from starpunk.websub_worker import start_worker - app.websub_worker = start_worker(app) + app.websub_worker = start_worker(app) if workers else None if app.websub_worker: app.logger.info("WebSub worker started") # Start syndication worker when a target is configured (v2.1.0) from starpunk.syndication import SyndicationWorker, targets_configured - if targets_configured(app.config) and not app.config.get("TESTING", False): + if workers and targets_configured(app.config) and not app.config.get("TESTING", False): app.syndication_worker = SyndicationWorker( app, poll_interval=app.config["SYNDICATION_POLL_INTERVAL"] ) @@ -465,5 +468,5 @@ def create_app(config=None): # Package version (Semantic Versioning 2.0.0) # See docs/standards/versioning-strategy.md for details -__version__ = "2.14.2" -__version_info__ = (2, 14, 2) +__version__ = "2.15.0" +__version_info__ = (2, 15, 0) diff --git a/starpunk/config.py b/starpunk/config.py index 8439dda..17fcf9d 100644 --- a/starpunk/config.py +++ b/starpunk/config.py @@ -113,6 +113,8 @@ def load_config(app, config_override=None): app.config["WEBSUB_MAX_SUBSCRIPTIONS"] = int(os.getenv("WEBSUB_MAX_SUBSCRIPTIONS", "1000")) app.config["WEBSUB_MAX_PER_HOST"] = int(os.getenv("WEBSUB_MAX_PER_HOST", "25")) app.config["WEBSUB_POLL_INTERVAL"] = int(os.getenv("WEBSUB_POLL_INTERVAL", "5")) + # Off in the MCP sidecar so it never runs a second set of workers (v2.15.0, ADR-075) + app.config["BACKGROUND_WORKERS_ENABLED"] = os.getenv("BACKGROUND_WORKERS_ENABLED", "true").lower() == "true" app.config["WEBMENTION_WORKER_ENABLED"] = os.getenv("WEBMENTION_WORKER_ENABLED", "true").lower() == "true" app.config["WEBMENTION_POLL_INTERVAL"] = int(os.getenv("WEBMENTION_POLL_INTERVAL", "10")) app.config["WEBMENTION_ERROR_BACKOFF"] = int(os.getenv("WEBMENTION_ERROR_BACKOFF", "60")) diff --git a/starpunk/indieauth.py b/starpunk/indieauth.py index ed1fa83..6889863 100644 --- a/starpunk/indieauth.py +++ b/starpunk/indieauth.py @@ -25,7 +25,11 @@ from starpunk.database import get_db from starpunk.utils import absolute_url_for CODE_LIFETIME_MINUTES = 10 -SUPPORTED_SCOPES = ["create", "update", "delete", "media", "profile"] +SUPPORTED_SCOPES = ["create", "update", "delete", "media", "draft", "profile"] + +# Scopes offered to an MCP client that asks for none (v2.15.0, ADR-075): +# the owner unticks what they don't want on the consent screen +MCP_DEFAULT_SCOPES = ["create", "update", "delete", "media", "draft"] class AuthorizationRequestError(Exception): @@ -56,6 +60,11 @@ def issuer() -> str: return current_app.config["SITE_URL"].rstrip("/") + "/" +def mcp_resource() -> str: + """The MCP endpoint's resource identifier (RFC 8707, v2.15.0)""" + return current_app.config["SITE_URL"].rstrip("/") + "/mcp" + + def admin_me() -> str: """The single identity StarPunk issues tokens for""" return current_app.config["ADMIN_ME"] @@ -134,7 +143,7 @@ def validate_authorization_request(params: Dict[str, str]) -> Dict[str, Any]: Returns: Normalized request: client_id, redirect_uri, state, scopes, - code_challenge + code_challenge, resource Raises: AuthorizationRequestError @@ -176,17 +185,31 @@ def validate_authorization_request(params: Dict[str, str]) -> Dict[str, Any]: scopes = [s for s in (params.get("scope") or "").split() if s] + # RFC 8707 resource indicator: only the MCP endpoint is a named resource + # here (v2.15.0, ADR-075). Micropub clients don't send one. + resource = (params.get("resource") or "").strip() or None + if resource is not None: + if resource.rstrip("/") != mcp_resource(): + raise AuthorizationRequestError( + "invalid_target", "Unknown resource; this server only issues tokens for its MCP endpoint" + ) + resource = mcp_resource() + if not scopes: + scopes = list(MCP_DEFAULT_SCOPES) + return { "client_id": client_id, "redirect_uri": redirect_uri, "state": params["state"], "scopes": scopes, "code_challenge": code_challenge, + "resource": resource, } def create_authorization_code( - client_id: str, redirect_uri: str, scope: str, code_challenge: str + client_id: str, redirect_uri: str, scope: str, code_challenge: str, + resource: Optional[str] = None, ) -> str: """Issue a single-use authorization code (stored hashed)""" code = secrets.token_urlsafe(32) @@ -195,8 +218,8 @@ def create_authorization_code( db.execute( """ INSERT INTO indieauth_codes - (code_hash, client_id, redirect_uri, scope, code_challenge, expires_at) - VALUES (?, ?, ?, ?, ?, ?) + (code_hash, client_id, redirect_uri, scope, code_challenge, expires_at, resource) + VALUES (?, ?, ?, ?, ?, ?, ?) """, ( _hash(code), @@ -205,6 +228,7 @@ def create_authorization_code( scope, code_challenge, datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(minutes=CODE_LIFETIME_MINUTES), + resource, ), ) db.commit() @@ -218,7 +242,7 @@ def redeem_authorization_code( Redeem an authorization code exactly once Returns: - {"me": ..., "scope": ..., "client_id": ...} + {"me": ..., "scope": ..., "client_id": ..., "resource": ...} Raises: InvalidGrantError @@ -240,7 +264,7 @@ def redeem_authorization_code( raise InvalidGrantError("Authorization code is invalid, expired or already used") row = db.execute( - "SELECT client_id, redirect_uri, scope, code_challenge FROM indieauth_codes WHERE code_hash = ?", + "SELECT client_id, redirect_uri, scope, code_challenge, resource FROM indieauth_codes WHERE code_hash = ?", (_hash(code),), ).fetchone() @@ -252,11 +276,20 @@ def redeem_authorization_code( if not secrets.compare_digest(challenge, row["code_challenge"]): raise InvalidGrantError("PKCE verification failed") - return {"me": admin_me(), "scope": row["scope"], "client_id": row["client_id"]} + return { + "me": admin_me(), + "scope": row["scope"], + "client_id": row["client_id"], + "resource": row["resource"], + } -def create_access_token(client_id: str, scope: str) -> Dict[str, Any]: - """Issue an access token (stored hashed); returns the token response""" +def create_access_token(client_id: str, scope: str, resource: Optional[str] = None) -> Dict[str, Any]: + """Issue an access token (stored hashed); returns the token response + + resource is the RFC 8707 resource the token is for (the MCP endpoint), + or None for Micropub tokens. + """ token = secrets.token_urlsafe(32) lifetime_days = current_app.config.get("INDIEAUTH_TOKEN_LIFETIME_DAYS", 90) expires_at = datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(days=lifetime_days) @@ -264,10 +297,10 @@ def create_access_token(client_id: str, scope: str) -> Dict[str, Any]: db = get_db(current_app) db.execute( """ - INSERT INTO indieauth_tokens (token_hash, client_id, scope, expires_at) - VALUES (?, ?, ?, ?) + INSERT INTO indieauth_tokens (token_hash, client_id, scope, expires_at, resource) + VALUES (?, ?, ?, ?, ?) """, - (_hash(token), client_id, scope, expires_at), + (_hash(token), client_id, scope, expires_at, resource), ) db.commit() @@ -286,14 +319,15 @@ def verify_access_token(token: str) -> Optional[Dict[str, Any]]: Check a bearer token issued by StarPunk Returns: - {"me", "client_id", "scope"} if active, otherwise None + {"me", "client_id", "scope", "resource", "expires_at"} if active, + otherwise None """ if not token: return None db = get_db(current_app) row = db.execute( """ - SELECT id, client_id, scope FROM indieauth_tokens + SELECT id, client_id, scope, resource, expires_at FROM indieauth_tokens WHERE token_hash = ? AND revoked_at IS NULL AND expires_at > datetime('now') """, (_hash(token),), @@ -306,7 +340,13 @@ def verify_access_token(token: str) -> Optional[Dict[str, Any]]: (row["id"],), ) db.commit() - return {"me": admin_me(), "client_id": row["client_id"], "scope": row["scope"]} + return { + "me": admin_me(), + "client_id": row["client_id"], + "scope": row["scope"], + "resource": row["resource"], + "expires_at": row["expires_at"], + } def revoke_access_token(token: str) -> None: @@ -334,7 +374,7 @@ def list_active_tokens() -> List[Dict[str, Any]]: db = get_db(current_app) rows = db.execute( """ - SELECT id, client_id, scope, created_at, expires_at, last_used_at + SELECT id, client_id, scope, resource, created_at, expires_at, last_used_at FROM indieauth_tokens WHERE revoked_at IS NULL AND expires_at > datetime('now') ORDER BY created_at DESC diff --git a/starpunk/mcp_server/__init__.py b/starpunk/mcp_server/__init__.py new file mode 100644 index 0000000..f40a504 --- /dev/null +++ b/starpunk/mcp_server/__init__.py @@ -0,0 +1,13 @@ +""" +MCP server for StarPunk (v2.15.0, ADR-075) + +AI clients (claude.ai connectors, Claude Code, ...) read and write notes +through the Model Context Protocol at SITE_URL/mcp. It runs as a sidecar +process (uvicorn, the official MCP Python SDK) next to the Flask app and +calls the same service functions. StarPunk's own IndieAuth server issues the +tokens; this server only checks them (an OAuth resource server). +""" + +from starpunk.mcp_server.server import create_asgi_app, create_mcp_server + +__all__ = ["create_asgi_app", "create_mcp_server"] diff --git a/starpunk/mcp_server/app.py b/starpunk/mcp_server/app.py new file mode 100644 index 0000000..f74ee48 --- /dev/null +++ b/starpunk/mcp_server/app.py @@ -0,0 +1,13 @@ +""" +ASGI entry point for the MCP sidecar (v2.15.0, ADR-075) + + uvicorn starpunk.mcp_server.app:app --host 0.0.0.0 --port 8001 + +Run it with BACKGROUND_WORKERS_ENABLED=false and the same environment and +data volume as the main app. Route /mcp and +/.well-known/oauth-protected-resource/mcp to it. +""" + +from starpunk.mcp_server.server import create_asgi_app + +app = create_asgi_app() diff --git a/starpunk/mcp_server/auth.py b/starpunk/mcp_server/auth.py new file mode 100644 index 0000000..5ad3b7d --- /dev/null +++ b/starpunk/mcp_server/auth.py @@ -0,0 +1,56 @@ +""" +Bearer token checks for the MCP endpoint (v2.15.0, ADR-075) + +Tokens are StarPunk IndieAuth tokens bound to the MCP resource (RFC 8707). +The SDK's bearer middleware turns a missing or rejected token into a 401 +that points the client at the protected resource metadata, and refuses +tokens whose resource isn't this endpoint (validate_token_resource). +""" + +from datetime import datetime, timezone +from typing import Optional + +import anyio.to_thread +from flask import Flask +from mcp.server.auth.provider import AccessToken + +from starpunk.indieauth import verify_access_token + + +def _epoch(value) -> Optional[int]: + """SQLite timestamp (datetime or 'YYYY-MM-DD HH:MM:SS' UTC) -> epoch seconds""" + if value is None: + return None + if isinstance(value, str): + try: + value = datetime.fromisoformat(value) + except ValueError: + return None + if value.tzinfo is None: + value = value.replace(tzinfo=timezone.utc) + return int(value.timestamp()) + + +class StarPunkTokenVerifier: + """TokenVerifier backed by the indieauth_tokens table""" + + def __init__(self, app: Flask): + self.app = app + + def _verify(self, token: str) -> Optional[AccessToken]: + with self.app.app_context(): + info = verify_access_token(token) + if not info: + return None + return AccessToken( + token=token, + client_id=info["client_id"], + scopes=(info["scope"] or "").split(), + expires_at=_epoch(info.get("expires_at")), + resource=info.get("resource"), + subject=info["me"], + ) + + async def verify_token(self, token: str) -> Optional[AccessToken]: + # Database work happens off the event loop + return await anyio.to_thread.run_sync(self._verify, token) diff --git a/starpunk/mcp_server/server.py b/starpunk/mcp_server/server.py new file mode 100644 index 0000000..506102b --- /dev/null +++ b/starpunk/mcp_server/server.py @@ -0,0 +1,95 @@ +""" +The MCP server and its ASGI app (v2.15.0, ADR-075) + +Stateless Streamable HTTP with plain JSON responses: every request stands +alone, so any number of uvicorn workers can serve it and nothing is lost on +restart. +""" + +from typing import Optional +from urllib.parse import urlparse + +from flask import Flask +from mcp.server import MCPServer +from mcp.server.auth.settings import AuthSettings +from mcp.server.transport_security import TransportSecuritySettings +from pydantic import AnyHttpUrl +from starlette.applications import Starlette + +from starpunk.mcp_server.auth import StarPunkTokenVerifier +from starpunk.mcp_server.tools import register_tools + +INSTRUCTIONS = """\ +StarPunk is an IndieWeb site: a personal blog of short notes and longer +articles, owned by one person. Notes are Markdown. A note whose first line +is '# Heading' is an article with that title. Notes can be drafts +(unpublished) or published; publishing may crosspost them to social +networks chosen with syndicate_to (see get_site_config). Prefer drafts unless +the owner asked to publish. Deleting is a soft delete that undelete_note +reverses. +""" + + +def _site(app: Flask) -> str: + return app.config["SITE_URL"].rstrip("/") + + +def create_mcp_server(app: Flask) -> MCPServer: + """The MCP server, with StarPunk's tools and token checks""" + site = _site(app) + server = MCPServer( + name="StarPunk", + instructions=INSTRUCTIONS, + website_url=site, + version=app.config.get("VERSION", ""), + token_verifier=StarPunkTokenVerifier(app), + auth=AuthSettings( + # Same string as the issuer in /.well-known/oauth-authorization-server + issuer_url=AnyHttpUrl(site + "/"), + resource_server_url=AnyHttpUrl(site + "/mcp"), + # Tools check their own scopes; any StarPunk token may connect + required_scopes=[], + validate_token_resource=True, + ), + ) + register_tools(server, app) + return server + + +def _transport_security(app: Flask) -> TransportSecuritySettings: + """Only requests for this site's host and from its origin (DNS rebinding)""" + site = urlparse(_site(app)) + hosts = [site.netloc] + origins = [f"{site.scheme}://{site.netloc}"] + if app.config.get("DEV_MODE"): + hosts += ["localhost:*", "127.0.0.1:*"] + origins += ["http://localhost:*", "http://127.0.0.1:*"] + return TransportSecuritySettings( + enable_dns_rebinding_protection=True, + allowed_hosts=hosts, + allowed_origins=origins, + ) + + +def create_asgi_app(app: Optional[Flask] = None) -> Starlette: + """ + ASGI app serving /mcp and its protected resource metadata + + Args: + app: The Flask app to call into. Built from the environment if not + given, with background workers off (the main app runs those). + """ + if app is None: + from starpunk import create_app + + app = create_app({"BACKGROUND_WORKERS_ENABLED": False}) + + server = create_mcp_server(app) + return server.streamable_http_app( + streamable_http_path="/mcp", + stateless_http=True, + json_response=True, + # Base64 photos for upload_media: 10 MB of image is ~14 MB encoded + max_request_body_size=16 * 1024 * 1024, + transport_security=_transport_security(app), + ) diff --git a/starpunk/mcp_server/tools.py b/starpunk/mcp_server/tools.py new file mode 100644 index 0000000..3367369 --- /dev/null +++ b/starpunk/mcp_server/tools.py @@ -0,0 +1,362 @@ +""" +MCP tools for StarPunk (v2.15.0, ADR-075) + +Reading tools call the notes, tags and search services. Writing tools build +a Micropub request and hand it to the Micropub handlers, so an MCP post goes +through exactly the same checks and side effects (scopes, drafts-only +tokens, crossposting, webmentions, WebSub) as one from any Micropub client. + +Scopes are the Micropub ones: reading needs any StarPunk token; drafts and +tags need create, update, delete or draft; writing needs create (or draft), +update, delete or media. +""" + +import base64 +import binascii +from pathlib import Path +from typing import Any, Callable, Optional +from urllib.parse import urlparse + +import anyio.to_thread +from flask import Flask +from mcp.server import MCPServer +from mcp.server.auth.middleware.auth_context import get_access_token +from mcp.server.mcpserver.exceptions import ToolError +from mcp.types import ToolAnnotations +from pydantic import BaseModel, Field + +from starpunk.indieauth import check_scope +from starpunk.micropub import MicropubError + +DRAFT_SCOPES = ("create", "update", "delete", "draft") +MAX_LIMIT = 100 + + +class Photo(BaseModel): + """A photo for a note""" + + url: str = Field(description="URL from upload_media, or any public image URL") + alt: str = Field(default="", description="Alt text describing the photo") + + +def _token_info() -> dict: + """The caller's token as the Micropub handlers expect it""" + token = get_access_token() + if token is None: + raise ToolError("Not authenticated") + return {"me": token.subject, "client_id": token.client_id, "scope": " ".join(token.scopes)} + + +def _require(info: dict, *scopes: str) -> None: + if not any(check_scope(s, info["scope"]) for s in scopes): + raise ToolError(f"This needs the {' or '.join(scopes)} scope; reconnect and grant it") + + +def _sees_drafts(info: dict) -> bool: + return any(check_scope(s, info["scope"]) for s in DRAFT_SCOPES) + + +def _clamp(limit: int) -> int: + return max(1, min(int(limit), MAX_LIMIT)) + + +def _note_url(slug: str) -> str: + from starpunk.utils import absolute_url_for + + return absolute_url_for("public.note", slug=slug) + + +def _summary(note) -> dict: + from starpunk.utils import iso_utc + + return { + "url": _note_url(note.slug), + "slug": note.slug, + "title": note.title, + "kind": note.kind, + "status": "published" if note.published else "draft", + "published": iso_utc(note.created_at), + "excerpt": note.excerpt, + } + + +def _find_note(url_or_slug: str): + """A note by its URL on this site or its slug""" + from starpunk.micropub import _note_from_url + from starpunk.notes import get_note + + value = (url_or_slug or "").strip() + if urlparse(value).scheme: + return _note_from_url(value) + note = get_note(slug=value.strip("/").split("/")[-1]) if value else None + if note is None: + raise ToolError("Note not found") + return note + + +def _status_after(url: str) -> dict: + """Summary of the note at url, as it is now""" + return _summary(_find_note(url)) + + +def register_tools(server: MCPServer, app: Flask) -> None: + """Add StarPunk's tools to the MCP server""" + site = app.config["SITE_URL"].rstrip("/") + + async def run(fn: Callable[..., Any], *args, **kwargs) -> Any: + """Run fn in a worker thread inside a Flask request context for SITE_URL""" + + def call(): + with app.test_request_context(base_url=site): + try: + return fn(*args, **kwargs) + except MicropubError as e: + raise ToolError(e.error_description or e.error) from e + except ValueError as e: + raise ToolError(str(e)) from e + + return await anyio.to_thread.run_sync(call) + + read_only = ToolAnnotations(read_only_hint=True, open_world_hint=False) + + # Reading + + @server.tool(annotations=read_only) + async def search_notes(query: str, include_drafts: bool = False, limit: int = 20) -> dict: + """Full-text search of the site's notes. Returns matches with a snippet; + use get_note for the whole note.""" + info = _token_info() + if include_drafts: + _require(info, *DRAFT_SCOPES) + + def search(): + from starpunk.search import has_fts_table, search_notes as fts + + db_path = Path(app.config["DATABASE_PATH"]) + if not has_fts_table(db_path): + raise ToolError("Search is not available on this server") + results = fts(query=query, db_path=db_path, published_only=not include_drafts, limit=_clamp(limit)) + return { + "results": [ + {"url": _note_url(r["slug"]), "slug": r["slug"], "title": r.get("title"), + "snippet": r.get("snippet")} + for r in results + ] + } + + return await run(search) + + @server.tool(annotations=read_only) + async def list_notes(include_drafts: bool = False, limit: int = 20, offset: int = 0) -> dict: + """The site's notes, newest first. Drafts are left out unless + include_drafts is true.""" + info = _token_info() + if include_drafts: + _require(info, *DRAFT_SCOPES) + + def notes(): + from starpunk.notes import list_notes as list_all + + found = list_all(published_only=not include_drafts, limit=_clamp(limit), offset=max(0, offset)) + return {"notes": [_summary(n) for n in found], "offset": max(0, offset)} + + return await run(notes) + + @server.tool(annotations=read_only) + async def get_note(url_or_slug: str) -> dict: + """One note in full: Markdown content, title (name), tags (category), + photos, status, reply/like/repost/bookmark target and crosspost links, + as Microformats2 properties.""" + info = _token_info() + + def one(): + from starpunk.micropub import note_to_mf2 + + note = _find_note(url_or_slug) + if not note.published and not _sees_drafts(info): + raise ToolError("Note not found") + return {"url": _note_url(note.slug), "slug": note.slug, + "properties": note_to_mf2(note)["properties"]} + + return await run(one) + + @server.tool(annotations=read_only) + async def list_tags(filter: str = "") -> dict: + """Tags in use on the site, most used first, optionally only those + containing filter.""" + info = _token_info() + _require(info, *DRAFT_SCOPES) + + def tags(): + from starpunk.micropub import _all_categories + + return {"tags": _all_categories(filter)} + + return await run(tags) + + @server.tool(annotations=read_only) + async def get_site_config() -> dict: + """What the site supports: post types and the crosspost targets + (syndicate-to uids) that create_note's syndicate_to accepts.""" + info = _token_info() + + def config(): + from starpunk.micropub import handle_query + + response = handle_query({"q": "config"}, info) + # Flask views may return (response, status[, headers]) + if isinstance(response, tuple): + response = response[0] + return response.get_json() + + return await run(config) + + # Writing + + @server.tool(annotations=ToolAnnotations(destructive_hint=False, open_world_hint=True)) + async def create_note( + content: str = "", + title: Optional[str] = None, + tags: Optional[list[str]] = None, + draft: bool = True, + photos: Optional[list[Photo]] = None, + in_reply_to: Optional[str] = None, + like_of: Optional[str] = None, + repost_of: Optional[str] = None, + bookmark_of: Optional[str] = None, + syndicate_to: Optional[list[str]] = None, + slug: Optional[str] = None, + published_at: Optional[str] = None, + ) -> dict: + """Create a note (Markdown). It is a draft unless draft is false; + publishing makes it public and crossposts it to the syndicate_to + targets. A title makes it an article. At most one of like_of, + repost_of and bookmark_of. published_at is an ISO 8601 date.""" + info = _token_info() + _require(info, "create", "draft") + + props: dict[str, list] = {"post-status": ["draft" if draft else "published"]} + if content: + props["content"] = [content] + if title: + props["name"] = [title] + if tags: + props["category"] = list(tags) + if photos: + props["photo"] = [{"value": p.url, "alt": p.alt} for p in photos] + for name, value in (("in-reply-to", in_reply_to), ("like-of", like_of), + ("repost-of", repost_of), ("bookmark-of", bookmark_of), + ("published", published_at)): + if value: + props[name] = [value] + data: dict[str, Any] = {"type": ["h-entry"], "properties": props} + if syndicate_to: + data["mp-syndicate-to"] = list(syndicate_to) + if slug: + data["mp-slug"] = slug + + def create(): + from starpunk.micropub import handle_create + + _, _, headers = handle_create(data, info) + return _status_after(headers["Location"]) + + return await run(create) + + @server.tool(annotations=ToolAnnotations(destructive_hint=True, idempotent_hint=True, open_world_hint=True)) + async def update_note( + url: str, + content: Optional[str] = None, + title: Optional[str] = None, + tags: Optional[list[str]] = None, + add_tags: Optional[list[str]] = None, + remove_tags: Optional[list[str]] = None, + draft: Optional[bool] = None, + photos: Optional[list[Photo]] = None, + in_reply_to: Optional[str] = None, + ) -> dict: + """Change a note. Only the fields given change: content replaces the + text, title replaces the title ("" removes it), tags replaces all + tags, add_tags/remove_tags adjust them, photos replaces all photos, + draft false publishes a draft (and crossposts it) and true unpublishes. + Edits to published notes follow to their crossposts.""" + info = _token_info() + _require(info, "update") + + replace: dict[str, list] = {} + if content is not None: + replace["content"] = [content] + if title is not None: + replace["name"] = [title] + if tags is not None: + replace["category"] = list(tags) + if draft is not None: + replace["post-status"] = ["draft" if draft else "published"] + if photos is not None: + replace["photo"] = [{"value": p.url, "alt": p.alt} for p in photos] + if in_reply_to is not None: + replace["in-reply-to"] = [in_reply_to] + data: dict[str, Any] = {"action": "update", "url": url, "replace": replace} + if add_tags: + data["add"] = {"category": list(add_tags)} + if remove_tags: + data["delete"] = {"category": list(remove_tags)} + + def update(): + from starpunk.micropub import handle_update + + note = _find_note(url) + data["url"] = _note_url(note.slug) + handle_update(data, info) + return _status_after(data["url"]) + + return await run(update) + + @server.tool(annotations=ToolAnnotations(destructive_hint=True, idempotent_hint=True, open_world_hint=False)) + async def delete_note(url: str) -> dict: + """Delete a note. It can be restored with undelete_note.""" + info = _token_info() + _require(info, "delete") + + def delete(): + from starpunk.micropub import handle_delete + + note_url = _note_url(_find_note(url).slug) + handle_delete({"url": note_url}, info) + return {"url": note_url, "status": "deleted"} + + return await run(delete) + + @server.tool(annotations=ToolAnnotations(destructive_hint=False, idempotent_hint=True, open_world_hint=False)) + async def undelete_note(url: str) -> dict: + """Restore a deleted note.""" + info = _token_info() + _require(info, "delete") + note_url = url if urlparse(url).scheme else f"{site}/note/{url.strip('/')}" + + def undelete(): + from starpunk.micropub import handle_delete + + handle_delete({"url": note_url}, info, undelete=True) + return _status_after(note_url) + + return await run(undelete) + + @server.tool(annotations=ToolAnnotations(destructive_hint=False, open_world_hint=False)) + async def upload_media(filename: str, data_base64: str) -> dict: + """Upload an image (JPEG, PNG, GIF, WebP or HEIC, base64-encoded) and + get its URL, to use as a photo in create_note or update_note.""" + info = _token_info() + _require(info, "media", "create") + try: + data = base64.b64decode(data_base64, validate=True) + except (binascii.Error, ValueError): + raise ToolError("data_base64 is not valid base64") + + def upload(): + from starpunk.media import save_media + + media = save_media(data, filename) + return {"url": f"{site}/media/{media['path']}"} + + return await run(upload) diff --git a/starpunk/routes/indieauth.py b/starpunk/routes/indieauth.py index 0d8d4fa..005c239 100644 --- a/starpunk/routes/indieauth.py +++ b/starpunk/routes/indieauth.py @@ -51,6 +51,7 @@ _REQUEST_FIELDS = ( "code_challenge", "code_challenge_method", "scope", + "resource", ) @@ -95,6 +96,11 @@ def metadata(): "revocation_endpoint_auth_methods_supported": ["none"], "scopes_supported": SUPPORTED_SCOPES, "response_types_supported": ["code"], + # Public clients only (PKCE); clients identify with a client_id + # URL whose JSON metadata lists redirect_uris, which is what MCP + # calls a Client ID Metadata Document (v2.15.0, ADR-075) + "token_endpoint_auth_methods_supported": ["none"], + "client_id_metadata_document_supported": True, "grant_types_supported": ["authorization_code"], "code_challenge_methods_supported": ["S256"], "authorization_response_iss_parameter_supported": True, @@ -158,6 +164,7 @@ def approve(): auth_request["redirect_uri"], " ".join(granted), auth_request["code_challenge"], + resource=auth_request["resource"], ) current_app.logger.info( f"IndieAuth: approved {auth_request['client_id']} (scope: {' '.join(granted) or 'none'})" @@ -209,7 +216,12 @@ def token(): # Spec: a code issued without scope cannot be used for an access token return _oauth_error("invalid_grant", "No scope was granted; use the authorization endpoint") - return _json(create_access_token(result["client_id"], result["scope"])) + # RFC 8707: a resource named here must be the one the code was issued for + requested = (request.form.get("resource") or "").strip().rstrip("/") + if requested and requested != (result["resource"] or ""): + return _oauth_error("invalid_target", "resource does not match the authorization request") + + return _json(create_access_token(result["client_id"], result["scope"], resource=result["resource"])) @bp.route("/auth/token", methods=["GET"]) @@ -222,7 +234,7 @@ def token_verify(): info = verify_access_token(token) if not info: return _oauth_error("unauthorized", "Invalid or expired access token", 401) - return _json(info) + return _json({k: info[k] for k in ("me", "client_id", "scope")}) @bp.route("/auth/revoke", methods=["POST"]) diff --git a/templates/admin/authorize.html b/templates/admin/authorize.html index 786986a..36dbd35 100644 --- a/templates/admin/authorize.html +++ b/templates/admin/authorize.html @@ -14,6 +14,11 @@ {{ auth_request.client_id }} wants to sign in as {{ me }}.

+ {% if auth_request.resource %} +

This is an AI assistant asking to use your site through MCP + ({{ auth_request.resource }}). It can read your notes and drafts, + and do whatever you allow below.

+ {% endif %}

After approval you will be sent to {{ auth_request.redirect_uri }}