Worklore

worklore-mcp

An MCP (Model Context Protocol) connector for worklore.dev — it lets any MCP-capable agent (Claude, ChatGPT, Cursor, …) search worklore's developer stories, read one with its capability disclosure attached, x-ray any skill or story before running it — all without an account — and, once you've signed in, record how a reproduction went, publish a story of your own, or revise one you published.

• Endpoint: https://worklore.dev/mcp (Streamable HTTP, JSON-RPC over POST)
• Auth: none to search and read public stories. Writes (and your private stories) use OAuth 2.1 (PKCE + dynamic client registration). Sign-in is with your GitHub public profile only — worklore sees your handle and avatar, no scopes, no email, no repositories.
• Listed on: the official MCP Registry as io.github.worklore/worklore, and Smithery
• Roadmap / progress: Project #1 (a "Relay Board" — the human does the site actions, the agent writes the code)

What it's for

worklore stories are text your agent *executes*. This connector brings them — and their capability tier — into your agent, so you can find relevant work and see what it can touch before you run it. Tiers describe reach (blast radius), not virtue, and this is never a "safe" verdict. See the write-up: Stop asking "is this skill safe?" — ask "what can it do?" and the tool it wraps, skill-xray.

Capability tiers: T0 inert · T1 local · T2 network · T3 elevated (secrets / persistence / privilege) · T4 opaque (fetches/runs code at runtime).

Tools

Read-only — no sign-in needed (public stories only; check_capability with a url needs sign-in, because the server fetches it for you):

Write — these act as you, and need your authenticated session:

All eight carry MCP annotations (readOnlyHint / openWorldHint / idempotentHint) so a client can tell the user what a call will do before they approve it, and all eight declare an outputSchema and return structuredContent, so a consuming agent can rely on shape instead of parsing prose.

Every result carries a human capability string (e.g. T0 · inert — touches nothing) so a tier code is never shown bare.

Resources

Since 0.6.0 resources/list is a fixed list of three documents — the same for everyone, every day — all readable without an account:

Stories are reached through one resource template, worklore://story/{slug} (resources/templates/list). Public stories read without a token; a private story reads only for its author and answers like a missing one to everyone else. Every worklore://story/… URI that resources/list handed out before 0.6.0 still reads. To *find* a story, use search_stories / suggest_for_project.

Why the stories left the list: a list that changes whenever someone publishes cannot be part of a surface fingerprint — the fingerprint would "break" every day without anything breaking, and teach clients to ignore a mismatch. The contents of the three documents may change between releases; the list entries may not without a new version.

Verify the surface yourself

A version number is a promise that nothing a client depends on changed without it. Since 0.6.0 worklore publishes its surface fingerprint in the shared form `mcp-surface/1` (SPEC, by Sidney Bissoli), so you check worklore exactly the way you check every other server that publishes it. The registry entry carries it in server.json under _meta → io.modelcontextprotocol.registry/publisher-provided → io.github.sidneybissoli/mcp-surface:

• declared.sha256 — the sha256 of what a client sees before it calls anything: the initialize result (protocol version, capabilities, instructions, serverInfo without its version) and the four lists (tools, resources, resource templates, prompts), normalised and serialised as the SPEC says;
• anonymous — which methods answer without a token (plus one named, harmless tools/call: check_capability on inline text), and its sha256.

The fastest check is Sidney's dependency-free verify.mjs (Node 18+). It reads the registry entry for the version, makes sure the endpoint can say "no" to a method that does not exist, captures the live surface, and compares:

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs

node verify.mjs io.github.worklore/worklore 0.7.0

Or in Python, with nothing installed (the declared hash only):

python3 - <<'PY'

import hashlib, json, urllib.request EP = "https://worklore.dev/mcp" def rpc(method, params=None): body = {"jsonrpc": "2.0", "id": 1, "method": method, **({"params": params} if params else {})} req = urllib.request.Request(EP, data=json.dumps(body).encode(), headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}) return json.load(urllib.request.urlopen(req)).get("result") def canon(v): # SPEC §3: keys by UTF-16 code unit, no whitespace, JSON.stringify strings if isinstance(v, dict): return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + canon(v[k]) for k in sorted(v, key=lambda s: s.encode("utf-16-be"))) + "}" if isinstance(v, list): return "[" + ",".join(canon(x) for x in v) + "]" return json.dumps(v, ensure_ascii=False) def listed(method, key): # this server answers each list in one page res = rpc(method) return res.get(key) if isinstance(res, dict) else None def by(items, key): return None if items is None else sorted(items, key=lambda x: str(x.get(key)).encode("utf-16-be")) init = rpc("initialize", {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "verify", "version": "1"}}) version = init"serverInfo" surface = {"initialize": {"protocolVersion": init.get("protocolVersion"), "capabilities": init.get("capabilities"), "instructions": init.get("instructions"), "serverInfo": {k: v for k, v in init["serverInfo"].items() if k != "version"}}, "tools": by(listed("tools/list", "tools"), "name"), "resources": by(listed("resources/list", "resources"), "uri"), "resourceTemplates": by(listed("resources/templates/list", "resourceTemplates"), "uriTemplate"), "prompts": by(listed("prompts/list", "prompts"), "name")} live = hashlib.sha256(canon(surface).encode()).hexdigest() entry = json.load(urllib.request.urlopen( "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.worklore%2Fworklore/versions/" + version)) published = entry"server""io.modelcontextprotocol.registry/publisher-provided""declared" print("version", version, "| live", live[:12], "| registry", published[:12], "| match" if live == published else "| DIFFERS") PY

If the version is the same and the hash differs, the server changed without saying so. Tell me in an issue. 0.5.1 published worklore's own per-section hashes under a surface key; 0.6.0 replaced them with this one shared format. The idea of publishing the fingerprint with each release came from a comment by @_firelinks under Sidney Bissoli's Your MCP server changed. Its version didn't.

What answers without a token

Since 0.5.0 one rule decides it, everywhere — the site, the REST API and this server alike. It lives as a single table in worklore's backend (access.py, rendered as docs/ACCESS.md); the summary below is generated from it.

The rule. Anyone can search and read all public stories without signing in — site, REST API and MCP alike. Private stories and every write (publish, edit, report a reproduction or a check, visibility, per-user d