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 <noreply@anthropic.com>
This commit is contained in:
PhilandClaude Opus 5.5 committed 2026-11-11 16:36:58 -07:00
1 parent 4ed2033cf9
commit 84411a16d9
27 files changed
+1248 -45

No files matched your search

+15
View File
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased] ## [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 ## [2.14.2] - 2026-11-10
### Added ### Added
+2
View File
@@ -78,6 +78,8 @@ USER starpunk
# Expose application port # Expose application port
EXPOSE 8000 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 # Health check
# Uses httpx (already in requirements) to verify app is responding # Uses httpx (already in requirements) to verify app is responding
+3
View File
@@ -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 - Built-in [IndieAuth](https://indieauth.spec.indieweb.org/) server for
Micropub apps (consent screen, tokens, revocation, Connected Apps page) Micropub apps (consent screen, tokens, revocation, Connected Apps page)
- Admin login through any OpenID Connect provider (e.g. Pocket ID) - 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, - [Webmention](https://www.w3.org/TR/webmention/): receiving (verified,
moderated, rate-limited) and sending; replies, quotes and mentions shown moderated, rate-limited) and sending; replies, quotes and mentions shown
on each note, with likes, reposts and replies as a line of counts with on each note, with likes, reposts and replies as a line of counts with
+2 -1
View File
@@ -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 | | [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 | | [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 | | [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) | | [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 | | [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) | | [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 ## Where to start
+5 -4
View File
@@ -2,7 +2,7 @@
**Version**: 2.14.0 (2026-11-10) **Version**: 2.14.0 (2026-11-10)
**Status**: Current. Verified against a database created by `create_app()` **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 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 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) | | `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` | | `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 | | `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 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. 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`. (primary key), `nonce`, `code_verifier` (PKCE), `next_url`, `expires_at`.
Consumed once on callback. 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`, `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`, **`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`. in `/admin/tokens`.
**Legacy tables, unused**: `auth_state` (v1 IndieLogin login state), `tokens` **Legacy tables, unused**: `auth_state` (v1 IndieLogin login state), `tokens`
+9
View File
@@ -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 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. 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, `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 feed and WebSub topic URLs, the IndieAuth issuer and redirect URIs, and to
decide whether the session cookie is `Secure`. 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` | | `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` | | `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `VERSION` | package `__version__` | Overrides the reported version; normally unset | | `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 ### Feeds
+77
View File
@@ -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)").
+11 -1
View File
@@ -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 | | 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) | | 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 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 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 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 OIDC) approves; the client exchanges the code at `/auth/token` (PKCE
required). Codes and tokens are stored hashed. Tokens last required). Codes and tokens are stored hashed. Tokens last
`INDIEAUTH_TOKEN_LIFETIME_DAYS` and can be revoked at `/auth/revoke` or in `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 - **Development**: `DEV_MODE=true` adds `/dev/login`, which logs in as
`DEV_ADMIN_ME` without any checks. Never enabled in production; start-up `DEV_ADMIN_ME` without any checks. Never enabled in production; start-up
logs a warning when it is on. logs a warning when it is on.
@@ -137,8 +137,10 @@ form `{"error", "error_description"}`.
"token_endpoint": "<SITE_URL>/auth/token", "token_endpoint": "<SITE_URL>/auth/token",
"revocation_endpoint": "<SITE_URL>/auth/revoke", "revocation_endpoint": "<SITE_URL>/auth/revoke",
"revocation_endpoint_auth_methods_supported": ["none"], "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"], "response_types_supported": ["code"],
"token_endpoint_auth_methods_supported": ["none"],
"client_id_metadata_document_supported": true,
"grant_types_supported": ["authorization_code"], "grant_types_supported": ["authorization_code"],
"code_challenge_methods_supported": ["S256"], "code_challenge_methods_supported": ["S256"],
"authorization_response_iss_parameter_supported": true "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 | | Value | 32 random bytes, URL-safe | 32 random bytes, URL-safe |
| Stored as | SHA-256 hash | SHA-256 hash | | Stored as | SHA-256 hash | SHA-256 hash |
| Lifetime | 10 minutes | `INDIEAUTH_TOKEN_LIFETIME_DAYS` (default 90) | | 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` `redeem_authorization_code` handles redemption for both `POST /auth/token`
and `POST /auth/authorize`: 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. 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 ### Verification and revocation
- `verify_access_token(token)` hashes the token and accepts it if it is - `verify_access_token(token)` hashes the token and accepts it if it is
neither revoked nor expired, then updates `last_used_at`. It returns 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 - `check_scope(required, scope)` matches whole words in the space-separated
scope string. scope string.
- Revocation sets `revoked_at`. It can happen by token value, through - 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` | | `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` | | `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_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`, `expires_at`, `last_used_at`, `revoked_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 The legacy v1 tables `auth_state`, `tokens` and `authorization_codes` are
not used (see the migration's header comment). not used (see the migration's header comment).
@@ -338,7 +351,6 @@ connection pinned, a 5-second limit).
Known gaps: Known gaps:
- `scopes_supported` leaves out `draft`, although Micropub honours it and - Unknown scopes are shown and granted as requested; they just have no
the consent screen grants it when requested. Unknown scopes are also shown effect. (`draft` has been listed in `scopes_supported` since v2.15.0.)
and granted as requested; they just have no effect.
- No token introspection endpoint and no refresh tokens. - No token introspection endpoint and no refresh tokens.
+3
View File
@@ -48,6 +48,8 @@ vulnerabilities (`pip-audit`); check again before each release.
| python-dotenv | `1.2.*` | Loading `.env` | | python-dotenv | `1.2.*` | Loading `.env` |
| Pillow | `13.0.*` | Image validation, resizing and variants; converting response avatars to 96 px WebP (`avatars.py`) | | 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) | | 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. `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 (`<indie-action>`), backfeed of responses from the silos | | 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 (`<indie-action>`), backfeed of responses from the silos |
| Login | OpenID Connect authorization code flow with PKCE (provider: Pocket ID) | | 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 | | 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 | | 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), Protocol details: [indieweb-protocols.md](indieweb-protocols.md),
+121
View File
@@ -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.
+4 -3
View File
@@ -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 Superseded ADRs are kept as history; their Status line names the ADR that
replaced them. replaced them.
**Total ADR files**: 70 (69 numbers: ADR-001 to ADR-044 and ADR-050 to **Total ADR files**: 71 (70 numbers: ADR-001 to ADR-044 and ADR-050 to
ADR-074, with two files numbered ADR-012). See [Numbering](#numbering). ADR-075, with two files numbered ADR-012). See [Numbering](#numbering).
Status values: **Accepted** (in force), **Superseded** (replaced by a later Status values: **Accepted** (in force), **Superseded** (replaced by a later
ADR), **Deprecated** (withdrawn, nothing replaces it; none at present), 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. | | [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. | | [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). | | [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 ### Operations, errors and monitoring
@@ -169,7 +170,7 @@ was carried out and is not itself superseded.
## How to create a new ADR ## 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`. 2. Name it `ADR-NNN-brief-descriptive-title.md`.
3. Follow the format of recent ADRs (e.g. ADR-070, ADR-071): 3. Follow the format of recent ADRs (e.g. ADR-070, ADR-071):
+6
View File
@@ -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;
+5 -1
View File
@@ -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. # Pinned to a minor series; see docs/architecture/technology-stack.md.
# Web framework and server # Web framework and server
@@ -25,3 +25,7 @@ apprise==2.2.*
# Images # Images
Pillow==13.0.* Pillow==13.0.*
pillow-heif==1.8.* pillow-heif==1.8.*
# MCP server sidecar (v2.15.0, ADR-075): official SDK, served by uvicorn
mcp==2.3.*
uvicorn==0.54.*
+8 -5
View File
@@ -325,9 +325,12 @@ def create_app(config=None):
register_error_handlers(app) 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) # Start webmention worker thread (v1.6.0 Phase 2)
# Per background-worker.md: Skip in test mode # 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 from starpunk.webmention_worker import WebmentionWorker
webmention_worker = WebmentionWorker( webmention_worker = WebmentionWorker(
app, app,
@@ -348,13 +351,13 @@ def create_app(config=None):
# Start WebSub worker (v2.10.0) # Start WebSub worker (v2.10.0)
from starpunk.websub_worker import start_worker 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: if app.websub_worker:
app.logger.info("WebSub worker started") app.logger.info("WebSub worker started")
# Start syndication worker when a target is configured (v2.1.0) # Start syndication worker when a target is configured (v2.1.0)
from starpunk.syndication import SyndicationWorker, targets_configured 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.syndication_worker = SyndicationWorker(
app, poll_interval=app.config["SYNDICATION_POLL_INTERVAL"] app, poll_interval=app.config["SYNDICATION_POLL_INTERVAL"]
) )
@@ -465,5 +468,5 @@ def create_app(config=None):
# Package version (Semantic Versioning 2.0.0) # Package version (Semantic Versioning 2.0.0)
# See docs/standards/versioning-strategy.md for details # See docs/standards/versioning-strategy.md for details
__version__ = "2.14.2" __version__ = "2.15.0"
__version_info__ = (2, 14, 2) __version_info__ = (2, 15, 0)
+2
View File
@@ -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_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_MAX_PER_HOST"] = int(os.getenv("WEBSUB_MAX_PER_HOST", "25"))
app.config["WEBSUB_POLL_INTERVAL"] = int(os.getenv("WEBSUB_POLL_INTERVAL", "5")) 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_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_POLL_INTERVAL"] = int(os.getenv("WEBMENTION_POLL_INTERVAL", "10"))
app.config["WEBMENTION_ERROR_BACKOFF"] = int(os.getenv("WEBMENTION_ERROR_BACKOFF", "60")) app.config["WEBMENTION_ERROR_BACKOFF"] = int(os.getenv("WEBMENTION_ERROR_BACKOFF", "60"))
+57 -17
View File
@@ -25,7 +25,11 @@ from starpunk.database import get_db
from starpunk.utils import absolute_url_for from starpunk.utils import absolute_url_for
CODE_LIFETIME_MINUTES = 10 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): class AuthorizationRequestError(Exception):
@@ -56,6 +60,11 @@ def issuer() -> str:
return current_app.config["SITE_URL"].rstrip("/") + "/" 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: def admin_me() -> str:
"""The single identity StarPunk issues tokens for""" """The single identity StarPunk issues tokens for"""
return current_app.config["ADMIN_ME"] return current_app.config["ADMIN_ME"]
@@ -134,7 +143,7 @@ def validate_authorization_request(params: Dict[str, str]) -> Dict[str, Any]:
Returns: Returns:
Normalized request: client_id, redirect_uri, state, scopes, Normalized request: client_id, redirect_uri, state, scopes,
code_challenge code_challenge, resource
Raises: Raises:
AuthorizationRequestError 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] 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 { return {
"client_id": client_id, "client_id": client_id,
"redirect_uri": redirect_uri, "redirect_uri": redirect_uri,
"state": params["state"], "state": params["state"],
"scopes": scopes, "scopes": scopes,
"code_challenge": code_challenge, "code_challenge": code_challenge,
"resource": resource,
} }
def create_authorization_code( 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: ) -> str:
"""Issue a single-use authorization code (stored hashed)""" """Issue a single-use authorization code (stored hashed)"""
code = secrets.token_urlsafe(32) code = secrets.token_urlsafe(32)
@@ -195,8 +218,8 @@ def create_authorization_code(
db.execute( db.execute(
""" """
INSERT INTO indieauth_codes INSERT INTO indieauth_codes
(code_hash, client_id, redirect_uri, scope, code_challenge, expires_at) (code_hash, client_id, redirect_uri, scope, code_challenge, expires_at, resource)
VALUES (?, ?, ?, ?, ?, ?) VALUES (?, ?, ?, ?, ?, ?, ?)
""", """,
( (
_hash(code), _hash(code),
@@ -205,6 +228,7 @@ def create_authorization_code(
scope, scope,
code_challenge, code_challenge,
datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(minutes=CODE_LIFETIME_MINUTES), datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(minutes=CODE_LIFETIME_MINUTES),
resource,
), ),
) )
db.commit() db.commit()
@@ -218,7 +242,7 @@ def redeem_authorization_code(
Redeem an authorization code exactly once Redeem an authorization code exactly once
Returns: Returns:
{"me": ..., "scope": ..., "client_id": ...} {"me": ..., "scope": ..., "client_id": ..., "resource": ...}
Raises: Raises:
InvalidGrantError InvalidGrantError
@@ -240,7 +264,7 @@ def redeem_authorization_code(
raise InvalidGrantError("Authorization code is invalid, expired or already used") raise InvalidGrantError("Authorization code is invalid, expired or already used")
row = db.execute( 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),), (_hash(code),),
).fetchone() ).fetchone()
@@ -252,11 +276,20 @@ def redeem_authorization_code(
if not secrets.compare_digest(challenge, row["code_challenge"]): if not secrets.compare_digest(challenge, row["code_challenge"]):
raise InvalidGrantError("PKCE verification failed") 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]: 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""" """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) token = secrets.token_urlsafe(32)
lifetime_days = current_app.config.get("INDIEAUTH_TOKEN_LIFETIME_DAYS", 90) lifetime_days = current_app.config.get("INDIEAUTH_TOKEN_LIFETIME_DAYS", 90)
expires_at = datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(days=lifetime_days) 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 = get_db(current_app)
db.execute( db.execute(
""" """
INSERT INTO indieauth_tokens (token_hash, client_id, scope, expires_at) INSERT INTO indieauth_tokens (token_hash, client_id, scope, expires_at, resource)
VALUES (?, ?, ?, ?) VALUES (?, ?, ?, ?, ?)
""", """,
(_hash(token), client_id, scope, expires_at), (_hash(token), client_id, scope, expires_at, resource),
) )
db.commit() db.commit()
@@ -286,14 +319,15 @@ def verify_access_token(token: str) -> Optional[Dict[str, Any]]:
Check a bearer token issued by StarPunk Check a bearer token issued by StarPunk
Returns: Returns:
{"me", "client_id", "scope"} if active, otherwise None {"me", "client_id", "scope", "resource", "expires_at"} if active,
otherwise None
""" """
if not token: if not token:
return None return None
db = get_db(current_app) db = get_db(current_app)
row = db.execute( 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') WHERE token_hash = ? AND revoked_at IS NULL AND expires_at > datetime('now')
""", """,
(_hash(token),), (_hash(token),),
@@ -306,7 +340,13 @@ def verify_access_token(token: str) -> Optional[Dict[str, Any]]:
(row["id"],), (row["id"],),
) )
db.commit() 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: def revoke_access_token(token: str) -> None:
@@ -334,7 +374,7 @@ def list_active_tokens() -> List[Dict[str, Any]]:
db = get_db(current_app) db = get_db(current_app)
rows = db.execute( 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 FROM indieauth_tokens
WHERE revoked_at IS NULL AND expires_at > datetime('now') WHERE revoked_at IS NULL AND expires_at > datetime('now')
ORDER BY created_at DESC ORDER BY created_at DESC
+13
View File
@@ -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"]
+13
View File
@@ -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()
+56
View File
@@ -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)
+95
View File
@@ -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),
)
+362
View File
@@ -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)
+14 -2
View File
@@ -51,6 +51,7 @@ _REQUEST_FIELDS = (
"code_challenge", "code_challenge",
"code_challenge_method", "code_challenge_method",
"scope", "scope",
"resource",
) )
@@ -95,6 +96,11 @@ def metadata():
"revocation_endpoint_auth_methods_supported": ["none"], "revocation_endpoint_auth_methods_supported": ["none"],
"scopes_supported": SUPPORTED_SCOPES, "scopes_supported": SUPPORTED_SCOPES,
"response_types_supported": ["code"], "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"], "grant_types_supported": ["authorization_code"],
"code_challenge_methods_supported": ["S256"], "code_challenge_methods_supported": ["S256"],
"authorization_response_iss_parameter_supported": True, "authorization_response_iss_parameter_supported": True,
@@ -158,6 +164,7 @@ def approve():
auth_request["redirect_uri"], auth_request["redirect_uri"],
" ".join(granted), " ".join(granted),
auth_request["code_challenge"], auth_request["code_challenge"],
resource=auth_request["resource"],
) )
current_app.logger.info( current_app.logger.info(
f"IndieAuth: approved {auth_request['client_id']} (scope: {' '.join(granted) or 'none'})" 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 # 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 _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"]) @bp.route("/auth/token", methods=["GET"])
@@ -222,7 +234,7 @@ def token_verify():
info = verify_access_token(token) info = verify_access_token(token)
if not info: if not info:
return _oauth_error("unauthorized", "Invalid or expired access token", 401) 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"]) @bp.route("/auth/revoke", methods=["POST"])
+5
View File
@@ -14,6 +14,11 @@
<strong>{{ auth_request.client_id }}</strong> wants to sign in as <strong>{{ auth_request.client_id }}</strong> wants to sign in as
<strong>{{ me }}</strong>. <strong>{{ me }}</strong>.
</p> </p>
{% if auth_request.resource %}
<p>This is an AI assistant asking to use your site through MCP
(<code>{{ auth_request.resource }}</code>). It can read your notes and drafts,
and do whatever you allow below.</p>
{% endif %}
<p><small>After approval you will be sent to {{ auth_request.redirect_uri }}</small></p> <p><small>After approval you will be sent to {{ auth_request.redirect_uri }}</small></p>
<form action="{{ url_for('indieauth.approve') }}" method="POST" class="login-form"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}"> <form action="{{ url_for('indieauth.approve') }}" method="POST" class="login-form"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
+2 -2
View File
@@ -5,7 +5,7 @@
{% block admin_content %} {% block admin_content %}
<div class="tokens-admin"> <div class="tokens-admin">
<h2>Connected Apps</h2> <h2>Connected Apps</h2>
<p>Micropub apps you have approved. Revoke any you no longer use.</p> <p>Micropub apps and AI assistants (MCP) you have approved. Revoke any you no longer use.</p>
{% if tokens %} {% if tokens %}
<div class="table-scroll"> <div class="table-scroll">
@@ -23,7 +23,7 @@
<tbody> <tbody>
{% for t in tokens %} {% for t in tokens %}
<tr> <tr>
<td>{{ t.client_id }}</td> <td>{{ t.client_id }}{% if t.resource %} <small>(MCP)</small>{% endif %}</td>
<td>{{ t.scope }}</td> <td>{{ t.scope }}</td>
<td>{{ t.created_at }}</td> <td>{{ t.created_at }}</td>
<td>{{ t.last_used_at or "never" }}</td> <td>{{ t.last_used_at or "never" }}</td>
+79 -1
View File
@@ -184,7 +184,9 @@ class TestCodesAndTokens:
with app.test_request_context(): with app.test_request_context():
code = create_authorization_code(CLIENT_ID, REDIRECT_URI, "create", challenge_for(verifier)) code = create_authorization_code(CLIENT_ID, REDIRECT_URI, "create", challenge_for(verifier))
result = redeem_authorization_code(code, CLIENT_ID, REDIRECT_URI, verifier) result = redeem_authorization_code(code, CLIENT_ID, REDIRECT_URI, verifier)
assert result == {"me": "https://example.com", "scope": "create", "client_id": CLIENT_ID} assert result == {
"me": "https://example.com", "scope": "create", "client_id": CLIENT_ID, "resource": None,
}
token = create_access_token(CLIENT_ID, "create") token = create_access_token(CLIENT_ID, "create")
info = verify_access_token(token["access_token"]) info = verify_access_token(token["access_token"])
@@ -354,3 +356,79 @@ class TestEndpoints:
admin_client.post(f"/admin/tokens/{token_id}/revoke") admin_client.post(f"/admin/tokens/{token_id}/revoke")
with app.test_request_context(): with app.test_request_context():
assert verify_access_token(token) is None assert verify_access_token(token) is None
MCP_RESOURCE = "https://blog.example.com/mcp"
class TestResourceIndicators:
"""RFC 8707 resource binding for MCP clients (v2.15.0, ADR-075)"""
def test_metadata_advertises_cimd_and_draft(self, client):
data = client.get("/.well-known/oauth-authorization-server").get_json()
assert data["client_id_metadata_document_supported"] is True
assert data["token_endpoint_auth_methods_supported"] == ["none"]
assert "draft" in data["scopes_supported"]
def test_mcp_resource_accepted(self, app):
with app.test_request_context():
result = validate_authorization_request(auth_params(resource=MCP_RESOURCE + "/"))
assert result["resource"] == MCP_RESOURCE
def test_no_resource_is_micropub(self, app):
with app.test_request_context():
assert validate_authorization_request(auth_params())["resource"] is None
def test_unknown_resource_rejected(self, app):
with app.test_request_context():
with pytest.raises(AuthorizationRequestError) as e:
validate_authorization_request(auth_params(resource="https://other.example/mcp"))
assert e.value.error == "invalid_target"
assert e.value.redirectable
def test_mcp_client_without_scope_is_offered_defaults(self, app):
with app.test_request_context():
result = validate_authorization_request(auth_params(scope="", resource=MCP_RESOURCE))
assert result["scopes"] == ["create", "update", "delete", "media", "draft"]
def test_consent_page_names_mcp(self, admin_client):
response = admin_client.get("/auth/authorize?" + urlencode(auth_params(resource=MCP_RESOURCE)))
assert response.status_code == 200
assert b"MCP" in response.data
assert b'name="resource" value="https://blog.example.com/mcp"' in response.data
def _token_form(self, query, **extra):
return {
"grant_type": "authorization_code",
"code": query["code"][0],
"client_id": CLIENT_ID,
"redirect_uri": REDIRECT_URI,
"code_verifier": "v" * 50,
**extra,
}
def test_resource_carried_to_token(self, app, admin_client, client):
query = approve(admin_client, granted=["create"], resource=MCP_RESOURCE)
body = client.post("/auth/token", data=self._token_form(query, resource=MCP_RESOURCE)).get_json()
with app.test_request_context():
info = verify_access_token(body["access_token"])
assert info["resource"] == MCP_RESOURCE
assert info["scope"] == "create"
def test_token_request_resource_must_match(self, admin_client, client):
query = approve(admin_client, granted=["create"], resource=MCP_RESOURCE)
response = client.post("/auth/token", data=self._token_form(query, resource="https://other.example/"))
assert response.status_code == 400
assert response.get_json()["error"] == "invalid_target"
def test_micropub_token_has_no_resource(self, app, admin_client, client):
query = approve(admin_client, granted=["create"])
body = client.post("/auth/token", data=self._token_form(query)).get_json()
with app.test_request_context():
assert verify_access_token(body["access_token"])["resource"] is None
def test_legacy_verification_shape_unchanged(self, app, client):
with app.test_request_context():
token = create_access_token(CLIENT_ID, "create", resource=MCP_RESOURCE)["access_token"]
data = client.get("/auth/token", headers={"Authorization": f"Bearer {token}"}).get_json()
assert data == {"me": "https://example.com", "client_id": CLIENT_ID, "scope": "create"}
+259
View File
@@ -0,0 +1,259 @@
"""
Tests for the MCP server (starpunk/mcp_server, v2.15.0, ADR-075)
Requests go through the real ASGI app (Streamable HTTP, stateless JSON) with
real StarPunk tokens, so the SDK's bearer checks, resource binding and DNS
rebinding protection are exercised along with the tools.
"""
import base64
import io
import json
import pytest
from PIL import Image
from starlette.testclient import TestClient
from starpunk.indieauth import create_access_token, revoke_access_token
from starpunk.mcp_server import create_asgi_app
SITE = "https://blog.example.com"
RESOURCE = SITE + "/mcp"
ALL_SCOPES = "create update delete media draft"
HEADERS = {
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
"MCP-Protocol-Version": "2025-11-25",
}
@pytest.fixture
def app(tmp_path):
from starpunk import create_app
data = tmp_path / "data"
return create_app(
{
"TESTING": True,
"SITE_URL": SITE,
"ADMIN_ME": "https://example.com",
"SESSION_SECRET": "test-secret",
"DATA_PATH": data,
"NOTES_PATH": data / "notes",
"DATABASE_PATH": data / "starpunk.db",
}
)
@pytest.fixture
def http(app):
with TestClient(create_asgi_app(app), base_url=SITE) as client:
yield client
@pytest.fixture
def token(app):
"""Make a token bound to the MCP resource (or another) with given scopes"""
def make(scope=ALL_SCOPES, resource=RESOURCE):
with app.app_context():
return create_access_token("https://claude.ai/client.json", scope, resource=resource)["access_token"]
return make
def rpc(http, token, method, params=None, headers=None):
body = {"jsonrpc": "2.0", "id": 1, "method": method}
if params is not None:
body["params"] = params
auth = {"Authorization": f"Bearer {token}"} if token else {}
return http.post("/mcp", json=body, headers={**HEADERS, **auth, **(headers or {})})
def call(http, token, name, **arguments):
"""Call a tool; returns (is_error, parsed JSON result or error text)"""
response = rpc(http, token, "tools/call", {"name": name, "arguments": arguments})
assert response.status_code == 200, response.text
result = response.json()["result"]
text = result["content"][0]["text"]
if result.get("isError"):
return True, text
return False, json.loads(text)
def ok(http, token, name, **arguments):
is_error, result = call(http, token, name, **arguments)
assert not is_error, result
return result
class TestAuth:
def test_no_token_points_to_resource_metadata(self, http):
response = rpc(http, None, "tools/list")
assert response.status_code == 401
assert f'resource_metadata="{SITE}/.well-known/oauth-protected-resource/mcp"' in (
response.headers["www-authenticate"]
)
def test_protected_resource_metadata(self, http):
data = http.get("/.well-known/oauth-protected-resource/mcp").json()
assert data["resource"] == RESOURCE
# Must equal the issuer in /.well-known/oauth-authorization-server
assert data["authorization_servers"] == [SITE + "/"]
def test_micropub_token_refused(self, http, token):
assert rpc(http, token(resource=None), "tools/list").status_code == 401
def test_other_resource_refused(self, http, token):
assert rpc(http, token(resource="https://other.example/mcp"), "tools/list").status_code == 401
def test_revoked_token_refused(self, app, http, token):
value = token()
with app.app_context():
revoke_access_token(value)
assert rpc(http, value, "tools/list").status_code == 401
def test_unknown_host_refused(self, http, token):
response = rpc(http, token(), "tools/list", headers={"Host": "evil.example"})
assert response.status_code in (400, 403, 421)
def test_lists_tools(self, http, token):
response = rpc(http, token(), "tools/list")
names = {t["name"] for t in response.json()["result"]["tools"]}
assert names == {
"search_notes", "list_notes", "get_note", "list_tags", "get_site_config",
"create_note", "update_note", "delete_note", "undelete_note", "upload_media",
}
def test_read_tools_are_marked_read_only(self, http, token):
tools = {t["name"]: t for t in rpc(http, token(), "tools/list").json()["result"]["tools"]}
assert tools["list_notes"]["annotations"]["readOnlyHint"] is True
assert tools["delete_note"]["annotations"]["destructiveHint"] is True
class TestWriting:
def test_create_defaults_to_draft(self, http, token):
note = ok(http, token(), "create_note", content="Hello from MCP", tags=["ai"])
assert note["status"] == "draft"
assert note["url"].startswith(SITE + "/note/")
def test_create_published_article(self, http, token):
tok = token()
note = ok(http, tok, "create_note", content="Body", title="An article", draft=False)
assert note["status"] == "published"
props = ok(http, tok, "get_note", url_or_slug=note["url"])["properties"]
assert props["name"] == ["An article"]
assert props["post-status"] == ["published"]
def test_draft_only_token_cannot_publish(self, http, token):
note = ok(http, token("draft"), "create_note", content="Sneaky", draft=False)
assert note["status"] == "draft"
def test_create_needs_scope(self, http, token):
is_error, message = call(http, token("update"), "create_note", content="x")
assert is_error and "create or draft" in message
def test_update_tags_and_publish(self, http, token):
tok = token()
note = ok(http, tok, "create_note", content="Tagged", tags=["one", "two"])
updated = ok(http, tok, "update_note", url=note["slug"], add_tags=["three"],
remove_tags=["one"], draft=False)
assert updated["status"] == "published"
props = ok(http, tok, "get_note", url_or_slug=note["slug"])["properties"]
assert props["category"] == ["two", "three"]
def test_update_content_and_remove_title(self, http, token):
tok = token()
note = ok(http, tok, "create_note", content="Old", title="Title")
ok(http, tok, "update_note", url=note["url"], content="New", title="")
props = ok(http, tok, "get_note", url_or_slug=note["url"])["properties"]
assert props["content"] == ["New"]
assert "name" not in props
def test_update_needs_scope(self, http, token):
note = ok(http, token(), "create_note", content="x")
is_error, _ = call(http, token("create"), "update_note", url=note["url"], content="y")
assert is_error
def test_delete_and_undelete(self, http, token):
tok = token()
note = ok(http, tok, "create_note", content="Gone soon", draft=False)
assert ok(http, tok, "delete_note", url=note["url"])["status"] == "deleted"
assert call(http, tok, "get_note", url_or_slug=note["slug"])[0]
assert ok(http, tok, "undelete_note", url=note["slug"])["status"] == "published"
def test_note_on_other_site_refused(self, http, token):
is_error, message = call(http, token(), "delete_note", url="https://other.example/note/x")
assert is_error and "not on this site" in message
def test_upload_media_then_attach(self, http, token):
tok = token()
buffer = io.BytesIO()
Image.new("RGB", (40, 30), "red").save(buffer, format="PNG")
media = ok(http, tok, "upload_media", filename="red.png",
data_base64=base64.b64encode(buffer.getvalue()).decode())
assert media["url"].startswith(SITE + "/media/")
note = ok(http, tok, "create_note", photos=[{"url": media["url"], "alt": "A red square"}])
props = ok(http, tok, "get_note", url_or_slug=note["slug"])["properties"]
assert props["photo"][0]["alt"] == "A red square"
def test_upload_rejects_bad_base64(self, http, token):
is_error, message = call(http, token(), "upload_media", filename="x.png", data_base64="!!!")
assert is_error and "base64" in message
class TestReading:
def test_list_hides_drafts_by_default(self, http, token):
tok = token()
ok(http, tok, "create_note", content="Draft")
ok(http, tok, "create_note", content="Public", draft=False)
assert [n["excerpt"] for n in ok(http, tok, "list_notes")["notes"]] == ["Public"]
assert len(ok(http, tok, "list_notes", include_drafts=True)["notes"]) == 2
def test_drafts_need_a_posting_scope(self, http, token):
ok(http, token(), "create_note", content="Secret draft")
reader = token("media")
assert call(http, reader, "list_notes", include_drafts=True)[0]
assert ok(http, reader, "list_notes")["notes"] == []
def test_draft_hidden_from_get_without_scope(self, http, token):
note = ok(http, token(), "create_note", content="Secret draft")
is_error, _ = call(http, token("media"), "get_note", url_or_slug=note["slug"])
assert is_error
def test_search(self, http, token):
tok = token()
ok(http, tok, "create_note", content="Pancakes on Sunday", draft=False)
ok(http, tok, "create_note", content="Waffles", draft=False)
results = ok(http, tok, "search_notes", query="pancakes")["results"]
assert len(results) == 1 and results[0]["url"].startswith(SITE + "/note/")
def test_tags(self, http, token):
tok = token()
ok(http, tok, "create_note", content="x", tags=["Cats", "dogs"])
assert set(ok(http, tok, "list_tags")["tags"]) == {"Cats", "dogs"}
assert ok(http, tok, "list_tags", filter="cat")["tags"] == ["Cats"]
def test_site_config(self, http, token):
config = ok(http, token("media"), "get_site_config")
assert config["media-endpoint"] == SITE + "/micropub/media"
assert "syndicate-to" in config
class TestSidecarApp:
def test_workers_off_when_built_from_environment(self, monkeypatch, tmp_path):
"""create_asgi_app() without an app never starts background workers"""
import starpunk
seen = {}
real = starpunk.create_app
def spy(config=None):
seen.update(config or {})
return real({**(config or {}), "TESTING": True, "SITE_URL": SITE,
"SESSION_SECRET": "x", "ADMIN_ME": "https://example.com", "DATA_PATH": tmp_path,
"NOTES_PATH": tmp_path / "notes", "DATABASE_PATH": tmp_path / "db.sqlite"})
monkeypatch.setattr(starpunk, "create_app", spy)
create_asgi_app()
assert seen["BACKGROUND_WORKERS_ENABLED"] is False