Files
StarPunk/starpunk/mcp_server/tools.py
T
PhilandClaude Opus 5.5 84411a16d9 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>
2026-11-11 16:36:58 -07:00

363 lines
13 KiB
Python

"""
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)