Merge branch 'feat/v2.15.0-mcp' for v2.15.0 release
Build Container / build (push) Successful in 9m40s
Build Container / build (push) Successful in 9m40s
This commit is contained in:
commit
9a0d82bab2
27 files changed
+1248
-45
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)").
|
||||
@@ -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.
|
||||
|
||||
@@ -137,8 +137,10 @@ form `{"error", "error_description"}`.
|
||||
"token_endpoint": "<SITE_URL>/auth/token",
|
||||
"revocation_endpoint": "<SITE_URL>/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.
|
||||
@@ -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 (`<indie-action>`), 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),
|
||||
|
||||
@@ -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.
|
||||
@@ -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):
|
||||
|
||||
|
||||
@@ -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
@@ -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.*
|
||||
@@ -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)
|
||||
@@ -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"))
|
||||
|
||||
+57
-17
@@ -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
|
||||
|
||||
@@ -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"]
|
||||
@@ -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()
|
||||
@@ -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)
|
||||
@@ -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),
|
||||
)
|
||||
@@ -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)
|
||||
@@ -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"])
|
||||
|
||||
@@ -14,6 +14,11 @@
|
||||
<strong>{{ auth_request.client_id }}</strong> wants to sign in as
|
||||
<strong>{{ me }}</strong>.
|
||||
</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>
|
||||
|
||||
<form action="{{ url_for('indieauth.approve') }}" method="POST" class="login-form"><input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
{% block admin_content %}
|
||||
<div class="tokens-admin">
|
||||
<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 %}
|
||||
<div class="table-scroll">
|
||||
@@ -23,7 +23,7 @@
|
||||
<tbody>
|
||||
{% for t in tokens %}
|
||||
<tr>
|
||||
<td>{{ t.client_id }}</td>
|
||||
<td>{{ t.client_id }}{% if t.resource %} <small>(MCP)</small>{% endif %}</td>
|
||||
<td>{{ t.scope }}</td>
|
||||
<td>{{ t.created_at }}</td>
|
||||
<td>{{ t.last_used_at or "never" }}</td>
|
||||
|
||||
+79
-1
@@ -184,7 +184,9 @@ class TestCodesAndTokens:
|
||||
with app.test_request_context():
|
||||
code = create_authorization_code(CLIENT_ID, REDIRECT_URI, "create", challenge_for(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")
|
||||
info = verify_access_token(token["access_token"])
|
||||
@@ -354,3 +356,79 @@ class TestEndpoints:
|
||||
admin_client.post(f"/admin/tokens/{token_id}/revoke")
|
||||
with app.test_request_context():
|
||||
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"}
|
||||
@@ -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
|
||||
Reference in new issue
Block a user