Hypothesis MCP — Specification

Author: Claude Code for jmpicnic Date: 2026-03-23 Status: Draft

Summary

Build a minimal stdio MCP server in TypeScript that lets Claude Code agents read and write Hypothesis web annotations. Then integrate it into the Arda workspace (settings, documentation, authoring guides) so future sessions can use it out of the box.

Context

• Goal file: Simple Hypothesis MCP
• Hypothesis is already used for documentation review — see the How to Comment on Documentation page.
• The MCP server will live in workspace/tools/mcp/hypothesis/.
• The 1Password item op://Private/Hypothesis-API/credential already exists for the project owner.

Scope

In Scope

1. MCP server implementation — TypeScript stdio server with 6 tools (adjusted for actual API).
2. MCP registration — Add the server to workspace/instructions/claude/settings.json.
3. Workspace docs — Add a Hypothesis section to workspace/mcp-setup.md.
4. Authoring docs — Update or extend the documentation site’s About/Authoring section with AI-assisted annotation workflows.
5. CI validation — All checks pass in both documentation/ and workspace/ before push.

Out of Scope

• Hypothesis browser extension setup (already covered in commenting.md).
• GitHub Actions CI for the MCP server itself (no CI pipeline exists for workspace/tools/).
• Real-time annotation streaming or WebSocket support.
• Target selectors for create_annotation (per goal file).

API Endpoint Corrections

The goal file specifies POST /api/bulk/annotation for get_group_annotations. This endpoint does not exist in the Hypothesis API. The corrected tool set:

Tool	Method	Actual Endpoint	Notes
get_groups	GET	/api/groups	Returns user’s group memberships
search_annotations	GET	/api/search	Params: group, uri, text, user, tag, limit, offset
get_annotation	GET	/api/annotations/{id}	Full annotation detail
get_group_annotations	GET	/api/search?group={pubid}	Paginated search filtered by group (replaces non-existent bulk endpoint)
create_annotation	POST	/api/annotations	Minimal payload — uri, text, group (default: arda-products), tags
update_annotation	PATCH	/api/annotations/{id}	Partial update — text, tags

The get_group_annotations tool will paginate internally using search_after or offset to fetch up to the requested limit (default 200).

Task Breakdown

#	Task	Phase	Depends On	Acceptance Criteria
T-1	Scaffold project: package.json, tsconfig.json, ESLint flat config, Prettier, Vitest config	1: MCP Server	—	npm install succeeds
T-2	Implement src/types.ts — shared types (Annotation, API response shapes)	1: MCP Server	T-1	npm run typecheck passes
T-3	Implement src/client.ts — Hypothesis API client (typed fetch wrapper)	1: MCP Server	T-2	Unit tests pass, correct URL construction
T-4	Implement src/index.ts — MCP server setup and tool registration	1: MCP Server	T-3	npm run build produces working dist/index.js
T-5	Write tests/client.test.ts — API client unit tests	1: MCP Server	T-3	All assertions pass with mocked fetch
T-6	Write tests/tools.test.ts — Tool input validation and response mapping tests	1: MCP Server	T-4	All assertions pass
T-7	Write README.md — Install, build, test, token setup, Claude Code config snippet	1: MCP Server	T-4	Contains all sections from goal file
T-8	Set up simple-git-hooks + lint-staged	1: MCP Server	T-1	Pre-commit hook runs Prettier + ESLint on staged .ts files
T-9	Run full validation: npm run build, npm run lint, npm test	1: MCP Server	T-5, T-6, T-8	Zero errors
T-10	Add Hypothesis MCP to settings.json (mcpServers section)	2: Integration	T-9	Valid JSON, uses op read for token
T-11	Add Hypothesis section to workspace/mcp-setup.md	2: Integration	T-9	Follows existing section format
T-12	Create/update authoring doc: AI-assisted annotation workflows	3: Documentation	T-9	New page or updated commenting.md covering agent read/write of annotations
T-13	Register new page in sidebar.json (if new file created)	3: Documentation	T-12	Page appears in sidebar under About
T-14	Run documentation/ CI checks: make test	3: Documentation	T-12, T-13	Build + link checks + smoke tests pass
T-15	Commit, push, create PRs for both repos	4: Ship	T-9, T-14	PRs created against main

Worktree Strategy

Two separate repositories are modified. Each gets its own worktree branched from main.

Worktree layout (at workspace root):

Worktree directory	Branch	Repository	Tasks
hypothesis-mcp-worktrees/workspace	jmpicnic/hypothesis-mcp	workspace	T-1 through T-11
hypothesis-mcp-worktrees/documentation	jmpicnic/hypothesis-mcp	documentation	T-12 through T-14

Merge workflow: Each worktree pushes its branch directly. One PR per repository, both targeting main.

Agent absolute-path rule: All tool calls use absolute paths to the worktree directories.

Phase Details

Phase 1: MCP Server (T-1 through T-9)

Worktree: hypothesis-mcp-worktrees/workspace

Build the complete MCP server under tools/mcp/hypothesis/. Follow all constraints from the goal file:

• No classes — plain functions only
• src/ under 300 lines total
• ESM ("type": "module")
• node: protocol prefix on built-in imports
• No any types
• exactOptionalPropertyTypes: true

STOP — Review checkpoint after Phase 1

All code must compile, lint, and test before proceeding.

Phase 2: Workspace Integration (T-10 through T-11)

Same worktree as Phase 1.

• Add the MCP server config to settings.json using the 1Password pattern.
• Add a documentation section to mcp-setup.md following the established format (Purpose, Prerequisites, Configuration, Verification).
• Include a note about first-session permission prompts and what each tool does.
• Include instructions for creating the 1Password item for other users.

Phase 3: Documentation Site (T-12 through T-14)

Worktree: hypothesis-mcp-worktrees/documentation

Create a new page about/authoring/using-hypothesis-with-agents.md covering:

1. Commenting on published docs with AI — How an agent can use the MCP to search and read annotations on documentation pages, then create annotations with feedback or suggestions.
2. Reading and responding to comments during authoring — How an agent working in the documentation/ repo can fetch annotations for the page being edited, address feedback in the source, and reply to or resolve annotation threads.
3. Practical examples — Sample prompts a user might give Claude Code to trigger these workflows.
4. Tool reference — Brief description of each MCP tool and what it returns.
5. Setup prerequisites — Link to commenting.md for Hypothesis account setup, link to mcp-setup.md for MCP server setup, note about 1Password item creation.

Also update commenting.md to cross-link to the new agent page.

Register the new page in sidebar.json under about > Authoring.

Run make test in the documentation worktree.

Phase 4: Ship (T-15)

• Commit all changes in each worktree.
• Push both branches.
• Create PRs targeting main in each repo.

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Hypothesis API rate limiting during development	Low	Low	All tests mock fetch; no real API calls in CI
search_after pagination not available	Medium	Low	Fall back to offset pagination
Documentation build breaks from new page	Low	Medium	Run make test before commit

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	New page vs. extend commenting.md for agent workflows?	A) New dedicated page; B) Add section to commenting.md	A) New page — keeps human and agent workflows separate, avoids bloating commenting.md	New page using-hypothesis-with-agents.md
2	Replace get_group_annotations tool entirely or keep as a convenience wrapper?	A) Drop it, users just call search_annotations with group param; B) Keep as convenience wrapper with internal pagination	B) Keep it — the paginated fetch-all pattern is useful and matches the original intent	Keep as paginated wrapper
3	How to handle pagination in get_group_annotations?	A) offset param; B) search_after cursor	A) offset — simpler, sufficient for expected dataset sizes (< 1000 annotations per group)	Use offset pagination