worklore

worklore-mcp

面向 worklore.dev 的 MCP（Model Context Protocol）连接器 — 它让任何支持 MCP 的 Agent（Claude、ChatGPT、Cursor，……）都能搜索 worklore 的开发者故事，阅读附带能力披露的故事，并在运行任何技能或故事前对其进行 X 光检查 — 全程无需账户。登录后，还可以记录复现结果、发布自己的故事，或修改已发布的故事。

• 端点： https://worklore.dev/mcp（Streamable HTTP，通过 POST 使用 JSON-RPC）
• 身份验证： 搜索和阅读公开故事无需身份验证。写入内容（以及你的私人故事）使用 OAuth 2.1（PKCE + 动态客户端注册）。登录仅使用你的 GitHub 公开资料 — worklore 会看到你的用户名和头像，不会获取任何权限范围、电子邮件或代码仓库。
• 已收录于：官方 MCP Registry，名称为 io.github.worklore/worklore，以及 Smithery
• 路线图 / 进展：项目 #1（一个“Relay Board” — 由人执行网站操作，Agent 编写代码）

用途

worklore 故事是 Agent 会执行的文本。这个连接器会将它们及其能力级别引入你的 Agent，让你能够找到相关内容，并在运行前了解它能触及什么。级别描述的是能力范围（影响半径），而非优劣；这绝不代表它“安全”。请参阅说明文章： 别再问“这个技能安全吗？”— 应该问“它能做什么？” 以及它封装的工具 skill-xray。

能力级别：T0 无操作 · T1 本地 · T2 网络 · T3 提权（机密信息 / 持久化 / 权限） · T4 不透明（运行时获取 / 执行代码）。

工具

只读——无需登录（仅限公开故事；check_capability 使用 url 时需要登录，因为服务会代你获取该 URL）：

工具	参数	返回内容
check_capability	text 或 url	等级（T0–T4）+ sha256 + 发现项（file:line）+ 端点，以及行为方面的危险信号——能力披露
get_story	slug	故事的完整 Markdown（叙述 + “Reproduce this” 合约），附带其能力等级 + 发现项
search_stories	query （可选）	匹配的故事（标题/摘要/标签/技术栈），每个都附带其能力说明
suggest_for_project	context	最多 3 个值得在此处复现的故事，并说明理由 + 等级

写入——这些工具会以你的身份操作，并且需要你的已认证会话：

工具	参数	返回内容
report_reproduction	slug、result（worked/partial/failed）、note （可选）	已记录的复现结果。failed 也是有用的报告，绝不可夸大
report_check	slug、result（has_problem/no_problem）、note （可选）	在你的项目中运行故事的只读“Check if this applies to you”部分后记录的结果。仅适用于有该部分的故事（get_story 会显示 has_check: true）。绝不可记录“不适用”——如果你的项目不符合检查的前提条件，请勿调用。每人每个故事只能记录一个结果；最新结果会替换之前的结果
publish_story	markdown，或各部分（title、narrative、reproduce、tags、type、stack）	已发布故事的 slug + URL。只有在作者明确批准完整草稿后，才可调用此工具
edit_story	slug、markdown（完整修订后的故事）、kind（rephrase/addition/correction，默认 rephrase）、note （更正时必填）、source （可选 https URL）	slug、URL、已记录的 revision（at、kind、note、source），以及已收到通知的复现者人数。只有故事作者可以编辑。**请先向作者展示修改前后的差异并获得批准。**故事的 date 永不更改。如果故事中有错误，应使用 correction，以便告知所有复现过该故事的人——绝不可用 rephrase
suggest_edit	slug、markdown（你建议的完整故事）、rationale（一两行：说明哪里有误或已过时，以及你做了哪些修改）	建议的 id、其 status（open）、故事 URL 和说明。对于他人的故事——这是 worklore 的拉取请求。**请先向用户展示修改前后的差异并获得批准。**故事不会因此改变：作者会收到通知，并可选择接受为署名修订或拒绝；也可选择将文本交还给用户，作为其自己故事的草稿。每人每个故事只能提交一条待处理建议；再次提交会替换原建议。对于用户自己的故事，请使用 edit_story

这八个工具都带有 MCP 注解（readOnlyHint / openWorldHint / idempotentHint），因此客户端可以在用户批准前告知其调用会产生什么效果；它们也都声明了 outputSchema 并返回 structuredContent，因此使用它们的 Agent 可以依赖数据结构，而不必解析散文文本。

每个结果都附带人类可读的能力说明（例如 T0 · inert — touches nothing），因此绝不会单独显示等级代码。

资源

从 0.6.0 开始，resources/list 是包含三份文档的固定列表——对所有人都相同，每天也不变，且无需账号即可读取：

URI	内容
worklore://guide	如何通过 MCP 使用 worklore：搜索、与用户一起阅读故事后再采取行动、复现故事、如实报告（failed 也有参考价值）、使用 check_capability 探查不熟悉的技能和提示词、仅在用户批准后发布或编辑
worklore://story-format	故事格式：frontmatter 字段、叙述内容、“复现此内容”约定（前置条件／Agent 需要用户提供的内容／步骤／验证）、可选的只读检查、失败故事、提案、清理敏感信息、精确引用规则。撰写故事前请先阅读
worklore://access	哪些内容无需令牌即可获取，哪些需要登录——根据服务强制执行的唯一访问表生成

故事通过一个资源模板 worklore://story/{slug} 获取 （resources/templates/list）。公开故事无需令牌即可读取；私有故事仅作者本人可读，对其他人则会像不存在一样。0.6.0 之前 resources/list 提供的所有 worklore://story/… URI 仍然可读。要查找故事，请使用 search_stories / suggest_for_project。

故事为何不再列在列表中：每当有人发布故事，列表都会变化，因此无法将其纳入界面指纹——即使一切正常，指纹也会每天“失效”，还会让客户端学会忽略不匹配的情况。三份文档的内容可能随版本发布而变化；列表条目则不能变，除非发布新版本。

自行验证界面

版本号意味着客户端所依赖的内容不会在未告知的情况下发生变化。从 0.6.0 开始，worklore 按照通用格式 mcp-surface/1 发布其界面指纹（由 Sidney Bissoli 编写的 SPEC），因此验证 worklore 的方式与验证其他所有发布该指纹的服务完全相同。注册表条目在 server.json 的 _meta → io.modelcontextprotocol.registry/publisher-provided → io.github.sidneybissoli/mcp-surface 下包含该指纹：

• declared.sha256——客户端调用任何内容之前所能看到内容的 sha256：initialize 结果（协议版本、功能、说明、去掉版本号的 serverInfo）以及四个列表（工具、资源、资源模板、提示词），并按 SPEC 所述进行标准化和序列化；
• anonymous——哪些方法无需令牌即可响应（另加一个指定的、无害的 tools/call：对内联文本执行 check_capability），以及其 sha256。

最快的检查方式是使用 Sidney 编写的无依赖项 verify.mjs （Node 18+）。它会读取该版本的注册表条目，确认端点能够对不存在的方法返回“否”，捕获实时界面并进行比较：

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

或者使用 Python，无需安装任何内容（仅检查声明的哈希）：

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"]["version"]
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"]["_meta"]["io.modelcontextprotocol.registry/publisher-provided"][
    "io.github.sidneybissoli/mcp-surface"]["declared"]["sha256"]
print("version", version, "| live", live[:12], "| registry", published[:12],
      "| match" if live == published else "| DIFFERS")
PY

如果版本相同而哈希不同，说明服务发生了变化，却没有告知。请在 issue 中告诉我。0.5.1 在 surface 键下发布了 worklore 自身按分区划分的哈希；0.6.0 用这一通用格式取代了它们。每次发布时一并发布指纹的想法，源自 @_firelinks 在 Sidney Bissoli 的 Your MCP server changed. Its version didn't. 下方发表的评论。

无需令牌即可获取的响应

从 0.5.0 起，一条规则决定了所有情况——网站、REST API 和本服务皆如此。这条规则以一张表的形式存放在 worklore 的后端（access.py，渲染为 docs/ACCESS.md）；以下摘要由该表生成。

规则。 无需登录，任何人都可以搜索和阅读所有公开故事——无论是在网站、REST API 还是 MCP 上。私有故事和所有写入操作（发布、编辑、报告复现或检查、可见性、用户数据，以及任何以某个人身份执行的操作）都需要已登录的会话。匿名读取会遵循唯一的可见性规则，因此私有故事的响应与不存在的故事完全相同。任何需要 worklore 代替他人付出成本的操作——例如让服务获取任意 URL——也需要会话，除非输入是内联文本。

• 无需凭据的方法：initialize、notifications/initialized、notifications/cancelled、ping、tools/list、resources/list、resources/read、resources/templates/list、prompts/list。
• 无需凭据的工具：search_stories、get_story、suggest_for_project、check_capability（不带 url）——仅限公开故事；私有故事的响应与不存在的故事完全相同。
• 需要已登录的会话：check_capability（带 url）、report_reproduction、report_check、publish_story、edit_story、suggest_edit。没有会话时，这些操作会返回 401，并附带指向授权服务器的 WWW-Authenticate 标头。
• 只有当 JSON-RPC 批次中的每条消息都无需令牌时，该批次才无需令牌即可响应。

实际上，你可以连接 worklore，无需账户即可搜索、阅读、获取建议，并对粘贴的文本进行 x-ray 分析。登录后，你可以查看自己的私有故事，让 check_capability 代你获取 URL，还可以让你的 Agent 记录复现或检查、发布或编辑——这些操作都会以你的身份执行。

历史。 在 0.4.0 之前，界限设在描述服务与使用服务之间：**列表和调用不必得到相同的响应。**匿名调用者可以获取服务的描述——名称、描述、输入和输出架构、注释——这些信息与 MCP Registry、Smithery 的列表以及本 README 中已公布的信息相同。他们无法执行任何操作、获取任何用户专属内容，也无法获得会话。0.5.0 保留了后两项限制，并开放了公开故事的读取；网站本来就从未限制过这项功能。

之所以将此事记录下来，是因为最初的做法是个错误。最初的构建版本限制了整个端点，理由听起来无懈可击：一道门，在一个地方把关。其后果在代码内部不可见，在外部却一目了然——一个镜像注册表的目录列出了 worklore 的名称和描述，却显示零个工具，因为爬虫无法以任何身份进行身份验证。同样的特性也意味着仓库之外的任何人——扫描器、一致性测试框架或好奇的陌生人——都无法检查该服务实际发布了什么。这是两个症状，同一个原因。修复只用了约 15 行：为匿名方法添加允许列表，并检查批次，从而防止特权调用混在匿名调用旁边偷偷通过。

完整说明、差异内容以及如何针对你自己的端点验证此修复，请见：我的 MCP 服务将自己的工具列表藏在登录墙后。如果有人提议限制你所维护服务的枚举功能，这篇文章是该论点的简明版。

对于工具名称属于敏感信息的服务，限制枚举是合理的选择。值得有意为之，而不是继承自传输层限制——多数情况正是如此，包括据其自身审计，促使本文记录此事的那个服务。

添加连接器

在 Claude Code 中：

claude mcp add --transport http worklore https://worklore.dev/mcp

**在 claude.ai（网页）上：**设置 → 连接器 → 添加自定义连接器 → 名称 worklore，网址 https://worklore.dev/mcp。（自定义连接器需要付费套餐。）

通过 Smithery：

npx -y smithery mcp add worklore/worklore

**其他 MCP 客户端：**将其指向 https://worklore.dev/mcp（Streamable HTTP）。搜索和阅读功能可立即使用；首次调用需要会话（写入操作，或对 URL 进行 x-ray）时，会返回 401，并引导你的客户端完成 OAuth 流程——客户端会自行注册，因此无需粘贴任何内容，也无需管理 API 密钥。

提示词示例

1. “使用 worklore 检查这个技能能做什么，再决定是否安装：<粘贴 URL 或技能文本>。”
2. “在 worklore 中搜索有关 Flutter golden 测试的案例，并告诉我每个案例的能力等级。”
3. “这是我的项目：一个使用 DynamoDB 的 Python AWS-Lambda 后端。请推荐 3 个值得在此复现的 worklore 案例，并读给我听排名第一的案例的 Reproduce-this 合约。”

说明

• 该连接器是 worklore 现有后端 Lambda 上的一条路由；它复用了随附的 skill-xray 扫描器。
• 会验证来源（原生客户端不会发送来源信息，因此会获准访问；未知网页来源会被拒绝）；强制使用 HTTPS。
• 了解此服务端如何从头到尾构建并发布，包括遇到的问题：构建并发布你自己的 MCP 服务。

采用 MIT 许可。