Skip to main content
Glama

GWL MCP 服务 v1(官方 Python SDK 实现)

把 GWL(gwl.net.cn)的 /api/v1 用户 API 封装成 MCP 服务:36 个工具 + 7 个资源, 传输支持 stdio(本地编程工具)与 Streamable HTTP / SSE(远程或多客户端)。

  • 上游权威定义:site-back/routes/api_v1.py(37 条路由)、API-WIKI.md §1.9、doc/API-V1-用户接口.md

  • 字段级清单:docs/API-INVENTORY.md(由代码生成,含每个端点的请求/响应/错误码)

  • 线上托管端点(不是本目录的代码):https://back.gwl.net.cn/mcp,说明见工作区 doc/MCP-服务.md

0. 与 v0 的区别

维度

mcp-server/v0(手写)

mcp-server/v1(本目录)

协议实现

纯标准库手写 JSON-RPC

官方 mcp Python SDK 2.3(协议版本由 SDK 协商,实测 2026-07-28)

传输

stdio + 极简 HTTP

stdio + Streamable HTTP + 旧版 SSE(双端点)

参数校验

手写检查

Pydantic 注解 → inputSchema 自动推导,SDK 侧强校验

结构化输出

无

outputSchema + structuredContent(客户端免解析文本)

资源

无

5 个静态 + 2 个模板资源

测试

少量

pytest 全套(单元 + 假上游集成 + 子进程 stdio + HTTP/SSE 传输)

定位

归档参考

推荐使用的实现

Related MCP server: listenbrainz-mcp

1. 安装

cd mcp-server/v1
python -m venv .venv                      # Windows: .venv\\Scripts\\python.exe
# 激活后或直接使用 venv 内的解释器
pip install -e ".[dev]"                    # 依赖:mcp>=2.3.0,<3(会带上 starlette/uvicorn/httpx)

实测环境:Windows 11 + Python 3.14.7 + mcp==2.3.0(mcp-types==2.3.0); 要求 python >= 3.10。装完后可用 gwl-mcp 命令,也可继续用 python run.py。

gwl-mcp --version            # 版本 + SDK 版本
gwl-mcp --list-tools         # 打印 36 个工具与上游端点对照
gwl-mcp --check              # 用当前环境变量真的打一次上游 /ping
gwl-mcp --transport stdio    # 本地 stdio 服务(默认)
gwl-mcp --transport http     # Streamable HTTP,默认 http://127.0.0.1:8765/mcp
gwl-mcp --transport sse      # 旧版 SSE:GET /sse + POST /messages/

2. 必填的两件事:身份

上游 /api/v1 用 数字 userid + gk_ 开头的 apikey 鉴权,两者都只走请求头 (X-User-Id / X-Api-Key),绝不出现在 URL、日志或返回值里。

  • userid:GWL 仪表盘「设置 - API Key」页面上显示的数字 id

  • apikey:同一页面创建,形如 gk_ + 43 位

3. 环境变量

完整模板见 .env.example(scripts/gen_configs.py 也照它渲染)。

变量

默认

说明

GWL_USER_ID

—

必填。数字用户 id

GWL_API_KEY

—

必填。gk_...;长度 16~200(与上游闸门一致)

GWL_API_BASE

https://back.gwl.net.cn/api/v1

上游基址;本地联调改 http://127.0.0.1:5000/api/v1

GWL_ALLOW_HTTP

0

上游基址是 http:// 时必须显式设 1(防明文泄露 key)

GWL_ORG_CLASS

空

3 位组类 id,作为 X-Org-Class 附带;不会因此提权

GWL_TIMEOUT

20

单次上游请求超时(秒,1~120)

GWL_TOTAL_TIMEOUT

60

单次工具调用(含全部重试与退避)的总墙钟预算(秒,5~300,且 ≥ GWL_TIMEOUT)

GWL_MAX_RETRIES

2

额外重试次数(0~5),见 §7 重试策略

GWL_ENABLE_WRITES

1

0 = 只读模式,12 个写工具在调用时报错(工具仍在列表里,避免客户端行为突变)

GWL_LOG_LEVEL

WARNING

DEBUG/INFO/WARNING/ERROR/CRITICAL;日志只写 stderr

GWL_ENV_FILE

空

指向一个 .env 文件(真实进程环境变量优先于文件)

GWL_HTTP_HOST

127.0.0.1

只影响 http/sse 传输

GWL_HTTP_PORT

8765

0~65535;填 0 表示让系统挑端口

GWL_HTTP_PATH

/mcp

Streamable HTTP 路径(sse 固定 /sse)

GWL_HTTP_AUTH_TOKEN

空

保护 MCP 端点本身的令牌(不是 GWL apikey),≥16 字符

GWL_HTTP_ALLOWED_ORIGINS

内置回环 + Inspector

额外允许的浏览器 Origin,逗号分隔(SDK 精确匹配,端口要写全)

GWL_HTTP_SESSION_TTL

1800

会话空闲回收(秒,60~86400)

GWL_HTTP_MAX_BODY_MB

16

请求体上限(MB,1~64)

GWL_HTTP_JSON_RESPONSE

0

1 = POST 一律用 application/json 回应,不升级 SSE(反代会缓冲 SSE 时更稳)

GWL_HTTP_ALLOW_INSECURE

0

明知风险时允许「非回环绑定 + 不设令牌」(不推荐)

绑非回环地址(如 0.0.0.0)却没设 GWL_HTTP_AUTH_TOKEN → 启动即 ConfigError 拒绝,不会裸奔。

4. 启动

4.1 stdio(本地编程工具)

GWL_USER_ID=12 GWL_API_KEY=gk_xxx python run.py --transport stdio
# Windows PowerShell:
$env:GWL_USER_ID=12; $env:GWL_API_KEY="gk_xxx"; .venv\\Scripts\\python.exe run.py --transport stdio

stdout 只有 JSON-RPC 帧;启动提示、日志、错误全部走 stderr。

4.2 Streamable HTTP

GWL_USER_ID=12 GWL_API_KEY=gk_xxx \\
GWL_HTTP_AUTH_TOKEN="$(openssl rand -hex 16)" \\
python run.py --transport http --host 127.0.0.1 --port 8765

端点 http://127.0.0.1:8765/mcp。客户端必须同时接受两种媒体类型: Accept: application/json, text/event-stream(只给 application/json 会 406,这是 SDK 行为)。 令牌三种给法任选:Authorization: Bearer <token>、Authorization: ApiKey <token>、X-MCP-Token: <token>; 缺失或错误 → 401 + JSON-RPC -32001(用常量时间比较,不泄露"前缀对不对")。

4.3 旧版 SSE(只认 SSE 的老客户端)

python run.py --transport sse --port 8766     # GET /sse 建流,POST /messages/ 发请求

4.4 让只支持 stdio 的客户端连远程 HTTP 服务

用官方 mcp-remote 做桥(模板:configs/stdio.bridge.mcp-remote.json)。

5. 客户端接入配置

configs/ 下 11 份模板,占位符统一是 <PYTHON_EXE>、<V1_DIR>、<GWL_USER_ID>、 <GWL_API_KEY>、<GWL_HTTP_AUTH_TOKEN>。用脚本一次渲染成可直接用的配置:

.venv/Scripts/python.exe scripts/gen_configs.py --user-id 12 --out configs/generated
# 或只打印一份:scripts/gen_configs.py --print cursor.mcp.json

模板

给谁用

传输

claude.desktop.json

Claude Desktop(claude_desktop_config.json)

stdio

claude.code.project.json

Claude Code(项目 .mcp.json)

stdio

cursor.mcp.json

Cursor(.cursor/mcp.json)

stdio

vscode.mcp.json

VS Code / GitHub Copilot(.vscode/mcp.json)

stdio

cline.mcp.json

Cline(mcp_settings.json)

stdio

continue.json

Continue(config.json 的 mcpServers 段)

stdio

windsurf.json

Windsurf(model_context_server_config.json)

stdio

generic.http.json

任何支持 Streamable HTTP + 自定义头的客户端

http

hosted.http.json

直接连线上托管 /mcp(用 userid+apikey 头,不用本目录代码)

http

stdio.bridge.mcp-remote.json

只认 stdio 但想连远程的客户端

stdio→http 桥

inspector.command.json

MCP Inspector 的 stdio 启动参数

stdio

每份文件都带 _readme 字段说明它放到哪里、要替换什么(_readme 是注释位,各家客户端都会忽略未知字段)。

6. 工具清单(36 个)

命名规则 gwl_<动词>_<对象>;类型列:读 = readOnlyHint,写 / 删 = 有副作用(删 另带 destructiveHint)。 每个工具的 _meta["gwl/upstream-endpoint"] 都写明它对应的上游方法+路径,gwl://tools/inventory 资源可直接读这张表。

工具

标题

上游端点

类型

必填参数

gwl_ping

连通性与凭据自检

GET /ping

读

—

gwl_get_me

我的资料

GET /me

读

—

gwl_get_permissions

实时权限快照

GET /permissions

读

—

gwl_list_my_classes

我的组类清单

GET /org/classes

读

—

gwl_list_my_orgs

我的组织树

GET /org/orgs

读

—

gwl_get_class

组类详情

GET /org/classes/{cid}

读

cid

gwl_list_joinable_classes

可加入的公开组

GET /org/joinable

读

—

gwl_get_join_info

组的加入状态

GET /org/classes/{cid}/join-info

读

cid

gwl_join_class

加入组类

POST /org/classes/{cid}/join

写

cid

gwl_list_my_join_requests

我提交的申请

GET /org/join-requests/mine

读

—

gwl_cancel_join_request

撤回我的申请

DELETE /org/join-requests/{request_id}

删

request_id

gwl_list_class_join_requests

组收到的申请

GET /org/classes/{cid}/join-requests

读

cid

gwl_review_join_request

审批加入申请

POST /org/join-requests/{request_id}/review

写

request_id

gwl_list_blacklist

组类黑名单

GET /org/classes/{cid}/blacklist

读

cid

gwl_add_to_blacklist

拉黑用户

POST /org/classes/{cid}/blacklist

写

cid, username

gwl_remove_from_blacklist

解除拉黑

DELETE /org/classes/{cid}/blacklist

写

cid, username

gwl_list_folders

文件夹列表

GET /folders

读

—

gwl_list_documents

文档列表(分页)

GET /documents

读

—

gwl_create_document

创建文档

POST /documents

写

title

gwl_list_my_documents

我的文档

GET /documents/mine

读

—

gwl_list_trash

我的回收站

GET /documents/trash

读

—

gwl_get_document

按 slug 读文档

GET /documents/{slug}

读

slug

gwl_get_document_by_id

按 id 读文档

GET /documents/id/{doc_id}

读

doc_id

gwl_update_document

更新文档(乐观锁)

PUT /documents/id/{doc_id}

写

doc_id

gwl_delete_document

删除文档(软删除)

DELETE /documents/id/{doc_id}

删

doc_id

gwl_list_document_revisions

修订历史

GET /documents/id/{doc_id}/revisions

读

doc_id

gwl_get_document_revision

某版修订全文

GET /documents/id/{doc_id}/revisions/{rev}

读

doc_id, rev

gwl_restore_document_revision

恢复到某版

POST /documents/id/{doc_id}/revisions/{rev}

写

doc_id, rev

gwl_restore_document

从回收站恢复

POST /documents/id/{doc_id}/restore

写

doc_id

gwl_search

标题搜索

GET /search

读

q

gwl_suggest_tags

标签联想

GET /tags/suggest

读

—

gwl_get_tag_facets

标签聚合

GET /tags/facets

读

object_type

gwl_get_object_tags

读对象标签

GET /tags/{object_type}/{object_id}

读

object_type, object_id

gwl_set_object_tags

全量替换对象标签

PUT /tags/{object_type}/{object_id}

写

object_type, object_id, tags

gwl_list_notifications

我的通知

GET /notifications

读

—

gwl_mark_notifications_read

标记通知已读

POST /notifications/read

写

—

刻意没有封装的工具:DELETE /documents/id/<id>/permanent(永久删除,不可逆, 且没有任何开关能打开)——与线上 site-back/services/mcp/tools.py 的决策一致。 37 条上游路由 - 1 条永久删除 = 36 个工具。

7. 资源(resource)

URI

内容

是否打上游

gwl://api/overview

基址、鉴权方式、限流口径、超时/重试策略、写保护状态(不含任何密钥)

否

gwl://tools/inventory

工具 ↔ HTTP 端点对照表(含只读/幂等/参数名)

否

gwl://me

当前 userid 的资料

是

gwl://permissions

实时权限快照

是

gwl://notifications

未读通知摘要

是

gwl://documents/by-id/{doc_id}

按 id 读文档(模板资源)

是

gwl://documents/by-slug/{slug}

按 slug 读文档(模板资源)

是

资源读取把上游 404 映射成 ResourceNotFoundError,其他错误映射成 ResourceError, 不会把上游原文(可能含敏感字段)整段抛给客户端。

8. 行为约定(照抄上游实现,不是设想)

8.1 请求

  • 鉴权头固定 X-User-Id / X-Api-Key(上游也接受 userid/apikey 与 Authorization: ApiKey|Bearer <key>,本实现统一用规范形式);设置了 GWL_ORG_CLASS 时附带 X-Org-Class。

  • 写请求体一律包成 {"data": {...}}(上游 api_v1 的入参约定),值为 None 的字段剔除,不发送客户端没填的键。

  • query 编码:None 丢弃、布尔转 1/0、列表转逗号分隔(与上游解析方式一致)。

  • 路径参数做 URL 编码(slug 里的空格会变 %20)。

  • User-Agent: gwl-mcp/2.0.0。禁止跟随重定向:3xx 一律当错误返回(带 key 的请求被重定向到别的 host 是泄露面)。

8.2 响应

上游统一信封 {code, msg, data},且 code 等于 HTTP 状态码;本服务在工具返回值里再加一层:

{ "ok": true, "msg": "成功", "data": { }, "rate_limit": { "remaining": 118, "reset_in": 12 } }

structuredContent 与 content[0].text 是同一份结构(客户端优先读 structuredContent)。 rate_limit 只在上游回 X-RateLimit-* 头时出现。

8.3 限流(上游实测口径,进程内 60 秒滑窗)

维度

上限

触发后

读(GET)

120/min/userid

429 + Retry-After

写(POST/PUT/DELETE)

30/min/userid

429 + Retry-After

IP 总量

240/min

429

鉴权失败

20/min

429(防爆破,此时别再重试)

8.4 超时与重试

  • 429:任何方法都重试(含 POST——上游限流是滑窗,重放不会造成重复副作用), 等待时间取 Retry-After 并夹在 1~30 秒;没有该头时用指数退避。

  • 5xx / 连接错误 / 超时:只重放 GET(幂等安全)。POST/PUT/DELETE 拿到 5xx 直接报错,绝不盲目重放。

  • 重试次数上限 GWL_MAX_RETRIES,并且始终受 GWL_TOTAL_TIMEOUT 总墙钟预算约束(预算用尽即停)。

8.5 错误返回

工具内部把错误转成 MCP 的 isError: true + 中文可执行提示 + 机读 JSON 尾巴,例如:

用户 ID 或 API Key 无效(HTTP 401)。请检查 GWL_USER_ID 与 GWL_API_KEY 是否匹配;
key 轮换或撤销后旧 key 会立即失效(key 只走请求头,不会进 URL 与日志)。
{"api_code": 401, "http_status": 401}

覆盖的状态码:400 / 401 / 403 / 404 / 409(附 current_version 等冲突信息)/ 413 / 429 / 5xx / 非 JSON 响应。 参数校验失败(必填缺失、枚举越界、类型不符、长度超限)由 SDK 的 Pydantic 校验直接报错,不会打到上游。 未声明的参数会被拒绝(列出允许的参数名),防止 page_size 这类近义拼错静默生效。

8.6 日志

configure() 只往 stderr 挂 handler(root 与 gwl_mcp),并把 httpx/uvicorn.access 等噪音降级; stdio 模式下 stdout 只有协议帧。工具调用会记一行 INFO(工具名、参数键名、结果、耗时), 不记录参数值,因此 key 与文档正文都不会进日志。

9. 测试

.venv/Scripts/python.exe -m pytest            # 全套(实测 182 项全绿,约 30 秒)
.venv/Scripts/python.exe -m pytest -k config  # 只跑配置校验

文件

覆盖

tests/test_config.py

环境变量解析、边界值、非回环必须令牌、.env 读取、脱敏摘要

tests/test_tools_contract.py

36 个工具的命名/描述/schema/注解/端点元数据;永久删除未暴露

tests/test_tool_requests.py

每个工具的 method/path/query/body 逐条比对(假上游抓包)+ 凭据只在头里

tests/test_api_client.py

信封解析、非 JSON、拒绝重定向、429 全方法重试、Retry-After 夹取、5xx 仅 GET、总预算、限流头、网络错误

tests/test_mcp_errors.py

错误映射不泄露 key、未知参数/枚举/类型拒绝、跨字段校验、只读模式、结果结构、日志内容

tests/test_http_transport.py

Streamable HTTP + SSE:406/401、会话头、DELETE、json_response 模式、Host 校验

tests/test_stdio_transport.py

子进程 stdio:握手、stdout 纯净(无日志污染)、每行一帧、未知工具、资源、tasks/get 未实现、无凭据泄露、退出码

tests/test_docs_and_configs.py

11 份客户端模板合法且无真实密钥、.env.example 覆盖全部变量、README/清单与代码同步

tests/fake_upstream.py

纯标准库假上游(回显 + 可编排状态码),测试与手工联调都用它

辅助脚本:

.venv/Scripts/python.exe scripts/probe_stdio.py   # 起真子进程走完整 stdio 链路,断言 36 工具/资源/校验
.venv/Scripts/python.exe scripts/serve_fake_upstream.py --port 5099   # 本地假上游(不含真实凭据)
.venv/Scripts/python.exe run.py --transport http --port 8765          # 另开一个终端
.venv/Scripts/python.exe scripts/probe_http.py --url http://127.0.0.1:8765/mcp --token <GWL_HTTP_AUTH_TOKEN>
.venv/Scripts/python.exe scripts/write_inventory.py   # 改了工具就重新生成 docs/API-INVENTORY.md

10. 验收记录(2026-11-22 本机实测,MCP Inspector v2.13.0)

客户端:npx -y @modelcontextprotocol/inspector --cli;上游:scripts/serve_fake_upstream.py(回显假上游,凭据 42 / gk_TESTONLY… ,不是真实 key)。

#

检查

传输

结果

1

initialize 握手

stdio / http / sse

通过;协议版本 2026-07-28(stdio 客户端)、2025-11-25(http 探测客户端);服务 gwl-api-mcp 2.0.0

2

tools/list

stdio

36 个;--strict 退出码 0(无 schema 可移植性错误);载荷 63,196 字节

3

schema 完整度

stdio

36/36 有 description、inputSchema.properties、annotations、_meta 端点、outputSchema

4

tools/call gwl_ping

stdio

ok:true,落到 GET /api/v1/ping;structuredContent 同步给出

5

tools/call gwl_list_documents(scope=public,page=2,size=5)

stdio

上游 query = scope=public, folder_id=0, page=2, size=5

6

tools/call gwl_create_document(写)

stdio

POST /api/v1/documents,body = {"data":{"title","slug","content"}}

7

未知参数 scope(该工具无此参数)

stdio

isError:true + 列出允许参数 content/folder_id/icon/owning/permission_bits/slug/summary/title/visibility

8

枚举越界 scope=nonsense

stdio

isError:true(Pydantic 校验信息),未打到上游

9

凭据无效(指向线上基址 + 占位 key)

stdio

isError:true + 401 中文提示 + {"api_code":401,"http_status":401};全文无 key

10

resources/list

stdio

5 个静态资源(2 个模板资源走 resources/templates/list)

11

resources/read gwl://tools/inventory

stdio

36 行对照表,含 endpoint/read_only/destructive/parameters

12

resources/read gwl://documents/by-id/7

stdio

模板 URI 解析为上游 GET /api/v1/documents/id/7

13

GWL_ENABLE_WRITES=0 + gwl_delete_document

stdio

isError:true「写操作已被禁用」;tools/list 仍是 36(读 24 / 写 12),行为可预期

14

无令牌 / 错令牌访问 /mcp

http

均 401(JSON-RPC -32001 + WWW-Authenticate)

15

tools/list、tools/call gwl_get_me、resources/read

http

36 工具;调用落到 GET /api/v1/me;资源 JSON 正常

16

tools/list、tools/call gwl_get_permissions

sse

36 工具;调用落到 GET /api/v1/permissions;无令牌 401

17

真实 MCP Client 接入(DeepSeek Harness 的 MCP 连接器)

stdio

导入即连接成功,Host 侧注册 36 个工具(健康检查 healthy),客户端读到的 gwl_ping schema 与 tools/list 一致

用真实 MCP Client 复现第 17 行

DSH / Claude Desktop / Cursor 这类客户端只要能吃 stdio 配置即可,例如通用 JSON(路径与凭据换成本机的):

{
  "mcpServers": {
    "gwl-mcp-v1": {
      "command": "D:/path/to/mcp-server/v1/.venv/Scripts/python.exe",
      "args": ["D:/path/to/mcp-server/v1/run.py", "--transport", "stdio"],
      "cwd": "D:/path/to/mcp-server/v1",
      "env": { "GWL_USER_ID": "12", "GWL_API_KEY": "gk_你的key", "GWL_LOG_LEVEL": "ERROR" }
    }
  }
}

连上之后先确认工具发现是 36 个,再调 gwl_ping(回报身份 + 限流口径); 401 是凭据问题,403 是权限问题(提示里会写清该去哪个页面看)。

11. 安全

  • 本仓库不含任何真实密钥:模板里是 <GWL_API_KEY> 占位符,测试里是 gk_TESTONLY… 假 key; .gitignore 排除 .env、.env.*(保留 .env.example)与 configs/*.local.json。 tests/test_docs_and_configs.py 会扫源码树,出现真实形状的 key 直接测试失败。

  • key 只走请求头;日志、错误消息、返回值都不含 key;拒绝重定向,避免跨 host 泄露。

  • HTTP/SSE 端点必须自带令牌(GWL_HTTP_AUTH_TOKEN,≥16 字符,常量时间比较); 非回环绑定不带令牌 → 启动失败(除非显式 GWL_HTTP_ALLOW_INSECURE=1)。

  • 复用 SDK 的 DNS-rebinding 防护:allowed_hosts 含回环名 + host:* 通配端口, allowed_origins 默认只放回环与 Inspector(6274/6277),可用 GWL_HTTP_ALLOWED_ORIGINS 追加。

  • 泄露处置:GWL 仪表盘「设置 - API Key」轮换,旧 key 立即失效(上游语义)。

12. 假设与待确认项

实现依据是 site-back/routes/api_v1.py + site-back/utils/api_v1.py 的代码事实;以下需要产品/上游确认:

  1. POST /documents 非幂等(重复调用会多一篇)。当前只在描述里提醒、idempotentHint=false, 没有做客户端幂等键;上游若支持 Idempotency-Key 可以再补一层。

  2. GET /documents/trash 的分页口径按代码同样是 page/size,上游文档未明写。

  3. 限流是进程内滑窗(多进程/多机部署会翻倍),所以本服务把 429 当作可重试信号而不是硬失败。

  4. 上游没有匿名健康检查端点,--check 借用 GET /ping(会消耗一次读额度)。

  5. X-Org-Class 只是「以某组类身份发请求」,判定仍在上游;本服务不做任何本地提权假设。

  6. MCP 的 logging 能力已被规范弃用(SEP-2577),因此不使用 ctx.log(),可观测性依赖 stderr 日志。

  7. 未封装 api-key 轮换 / 账号注销类接口:故意不让 MCP 客户端碰凭据生命周期。

13. 目录结构

gwl_mcp/
  config.py        环境变量 → Config(校验 + 脱敏摘要)
  api.py           上游 HTTP 客户端:头、信封、编码、超时/重试、错误映射
  errors.py        错误类型 + 每个状态码的中文提示
  runtime.py       工具调用落到 API 调用;参数严格校验;错误文本
  registry.py      gwl_tool 装饰器 + install(server)(注解、meta、ToolError 包装)
  params.py        复用的参数注解(cid/slug/page/size/tags…)
  resources.py     5 静态 + 2 模板资源
  server.py        MCPServer 组装、Bearer 中间件、http/sse app
  cli.py           命令行入口(--transport/--check/--list-tools/--version)
  tools/           account(3) / org(13) / documents(13) / taxonomy(5) / notifications(2)
configs/           11 份客户端配置模板 + generated/(渲染产物,忽略)
docs/API-INVENTORY.md  由代码生成的字段级清单
scripts/           gen_configs / probe_stdio / probe_http / serve_fake_upstream / write_inventory
tests/             pytest 全套 + 假上游
run.py             免安装直接跑:python run.py --transport stdio

14. 上游接口变了怎么同步

  1. 改/加 site-back/routes/api_v1.py 的路由;

  2. 在 gwl_mcp/tools/<域>.py 增删工具(endpoint 写清方法 + 路径模板);

  3. 更新 tests/test_tools_contract.py 的 EXPECTED_TOOLS / EXPECTED_ENDPOINTS;

  4. python scripts/write_inventory.py 重新生成 docs/API-INVENTORY.md;

  5. python -m pytest 全绿,并同步本 README §6 工具表(可直接从 tools/list 导出)。

Available Tools

36 tools
gwl_add_to_blacklist拉黑用户A

把一个用户加入组类黑名单(会同时给对方发一条站内通知)。 拉黑自己 400;已在名单里 409。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。

Inputs: cid (required), username (required), reason. Returns: object

gwl_cancel_join_request撤回我的申请A
DestructiveIdempotent

撤回我自己提交的加入申请,状态变为 cancelled。 只能撤自己的(否则 403);已被批准或拒绝过的再撤回会 409。 先用 gwl_list_my_join_requests 取 request_id。

Inputs: request_id (required). Returns: object

gwl_create_document创建文档A

创建一篇文档,返回文档详情(含 content,version=1)。 title 必填非空;slug 省略时上游按毫秒时间戳自动生成,已占用则 400。 写入范围(visibility/owning/folder_id/permission_bits)由服务端做写边界校验,越界返回 403;folder_id 不存在返回 400。 本工具不幂等:网络失败时不要盲目重试,先用 gwl_list_my_documents 确认是否已经建过。

Inputs: title (required), icon, slug, owning, +5 more. Returns: object

gwl_delete_document删除文档(软删除)A
DestructiveIdempotent

把文档移入回收站(软删除,可用 gwl_restore_document 恢复)。 仅作者或被授权者,否则 403;已经是回收站状态则 404。 不可恢复的永久删除接口本服务刻意不提供。

Inputs: doc_id (required). Returns: object

gwl_get_class组类详情A
Read-onlyIdempotent

读取某个组类的详细信息:id、name、kind、org_id、owner、role、can_manage、permissions[]、permission_map。 仅成员、owner、上级组织管理方或超管可见;不是成员 403,不存在 404,cid 不是 3 位字母 400。

Inputs: cid (required). Returns: object

gwl_get_document按 slug 读文档A
Read-only

按 slug 读取文档全文(返回字段随可见性做权限位掩码)。 ⚠️ 有副作用:每次命中都会 view_count + 1,因此标记为非幂等。 只是要读内容做编辑时,请改用 gwl_get_document_by_id(不加浏览数)。 不存在 404;无权查看 403。

Inputs: slug (required). Returns: object

gwl_get_document_by_id按 id 读文档A
Read-onlyIdempotent

按文档 id 读取全文,不增加浏览数,是编辑前的推荐读法。 返回里的 version 就是乐观锁基线,更新时原样带回 data.version。 软删除的文档只有作者或超管能看到,其他人 404。

Inputs: doc_id (required). Returns: object

gwl_get_document_revision某版修订全文A
Read-onlyIdempotent

读取某一版修订的全文,并带 current_version 与 can_restore。 该修订不存在 404;没有内容快照 404。

Inputs: rev (required), doc_id (required). Returns: object

gwl_get_join_info组的加入状态A
Read-onlyIdempotent

查询某组类的可见性与「我」的状态:is_public、joinable、is_member、blacklisted、request(我提交的待处理申请,没有则 null)。 这条不需要组类身份,任何人都能先探测再决定要不要申请加入。

Inputs: cid (required). Returns: object

gwl_get_me我的资料A
Read-onlyIdempotent

读取当前 API Key 所属用户的个人资料(与前端「个人中心」同源)。 返回 id、username、nickname、display_name、email、phone、avatar、theme、introduction、gender、location、group_id/group_name、slug、is_public、workspace_layout 等。 出于安全,永远不含 account_apikey、password_hash、pin;要拿权限等级请用 gwl_get_permissions。

Inputs: no named parameters. Returns: object

gwl_get_object_tags读对象标签A
Read-onlyIdempotent

读取某个对象当前的标签(裸数组 [{id,name}],按名称排序)。 能看到对象就能看到标签;看不到对象 404 / 403。 object_id 用字符串:文档传 doc_id,组织/组传 3 位 cid,发现条目传条目 id。

Inputs: object_id (required), object_type (required). Returns: object

gwl_get_permissions实时权限快照A
Read-onlyIdempotent

返回本次请求实时解析出的权限(服务端每次请求重算,不信任任何客户端声明)。 字段:userid、real_level、level、context(apikey 路径恒为 null)、nodes(5 段权限节点串列表)、class_id 与 class_role(当前组类身份)。 想以某个组类身份操作,用环境变量 GWL_ORG_CLASS(或请求级 X-Org-Class 语义),不属于该组类时会被静默忽略。

Inputs: no named parameters. Returns: object

gwl_get_tag_facets标签聚合A
Read-onlyIdempotent

按对象类型聚合标签用量,返回 {object_type, scope, items[{id,name,count}]}。 object_type 必填;scope 只对 document 生效;不支持的类型返回 400。

Inputs: object_type (required), limit, scope. Returns: object

gwl_join_class加入组类A

加入组类:public 组直接入组(data.mode=joined),private 组转为提交申请(data.mode=requested)。 已经是成员不会报错,会回 already_member=true(幂等)。 失败语义:组已停用 / 非公开且不允许申请 / 我在黑名单 403;cid 非法 400。message 最多 200 个字符。

Inputs: cid (required), role, message. Returns: object

gwl_list_blacklist组类黑名单A
Read-onlyIdempotent

列出该组类的黑名单(裸数组:user_id、username、reason、created_by、created_at)。 传组织 id 时汇总下辖组。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。

Inputs: cid (required). Returns: object

gwl_list_class_join_requests组收到的申请A
Read-onlyIdempotent

列出某组类收到的加入申请(裸数组,需管理权限)。 传组织 id 会汇总其下辖组的申请。status 默认 pending,可取 all / approved / rejected。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。

Inputs: cid (required), status. Returns: object

gwl_list_document_revisions修订历史A
Read-onlyIdempotent

列出文档的修订历史(裸数组:revision_num、editor_username、summary、has_content、created_at)。 不含正文;取某一版全文用 gwl_get_document_revision。

Inputs: doc_id (required). Returns: object

gwl_list_documents文档列表(分页)A
Read-onlyIdempotent

按范围列出文档元信息(不含正文),逐条判权后分页。 返回 {items,page,size,total,has_more};items 是 meta 视图,取正文用 gwl_get_document_by_id(不加浏览数)或 gwl_get_document(会 +1 浏览数)。 folder_id:0=根目录(默认)、-1=该范围下全部文件夹、正整数=指定文件夹。 deleted=1 只看回收站里的(需相应权限);author_id 只在 scope=public 生效。 tags 最多 8 个,tag_mode=all 表示同时命中,any 表示任一命中。

Inputs: page, size, tags, scope, +4 more. Returns: object

gwl_list_folders文件夹列表A
Read-onlyIdempotent

只列文件夹(不含文档),返回裸数组:id、name、scope、user_id、group_name、parent_id、sort_order、is_active、created_at、updated_at;group 范围的项还带 class_id/org_id/group_root。 scope 省略时返回我全部可见的文件夹;parent_id=0 只取根级,正整数只取该文件夹的直接子级,省略则返回全部层级。

Inputs: scope, parent_id. Returns: object

gwl_list_joinable_classes可加入的公开组A
Read-onlyIdempotent

列出所有允许自助加入的 public 组(返回裸数组,上限 200 条)。 class_id 可收窄到某个组织下的组;传了不属于任何组织的 id 会 400。

Inputs: class_id. Returns: object

gwl_list_my_classes我的组类清单A
Read-onlyIdempotent

平铺返回我加入或拥有的所有组类(组织 + 组),是找 cid 的入口。 每项含 id(3 位字母)、name、kind(organization/group)、org_id、owner、role、is_active、is_public、node、can_manage。 另带 status{tables_ready, missing, hint}:组织数据表未就绪时 hint 会说明原因。

Inputs: no named parameters. Returns: object

gwl_list_my_documents我的文档A
Read-onlyIdempotent

列出我自己的未删除文档(分页包络)。 folder_id 默认 0(只看根目录);要一次看全部请传 -1。

Inputs: page, size, folder_id. Returns: object

gwl_list_my_join_requests我提交的申请A
Read-onlyIdempotent

列出我提交过的加入申请(裸数组)。默认只返回待处理(pending)的; handled=true 时连已批准/已拒绝/已撤回的一起返回。 每项含 group、requester_username、reviewer_username、status、already_member。

Inputs: handled. Returns: object

gwl_list_my_orgs我的组织树A
Read-onlyIdempotent

返回我加入/拥有的组织,组织为顶层、下辖我可见的组(groups 数组)。 适合先看清层级关系,再决定用哪个 cid 去调用组类详情或黑名单类工具。

Inputs: no named parameters. Returns: object

gwl_list_notifications我的通知A
Read-onlyIdempotent

返回我的站内通知 + 我当前可见的全局通知 + 未读计数。 结构:{personal[], global[](带 is_read), unread{total,global,personal}}。 这不是分页包络,用 limit 截断(默认 100,最大 200)。

Inputs: limit. Returns: object

gwl_list_trash我的回收站A
Read-onlyIdempotent

列出被我软删除的文档(分页包络,按删除时间倒序)。 配合 gwl_restore_document 恢复;永久删除不提供工具。

Inputs: page, size. Returns: object

gwl_mark_notifications_read标记通知已读A

把指定通知标记为已读,返回新的未读计数 {unread{total,global,personal}}。 global_ids 与 personal_ids 至少要给一个且不能是空列表,否则本工具直接报错。 只能标记自己的通知;别人的 id 会被上游静默忽略。操作幂等(重复调用结果一致)。

Inputs: global_ids, personal_ids. Returns: object

gwl_ping连通性与凭据自检A
Read-onlyIdempotent

验证当前 userid + apikey 是否可用,并返回身份信息与本进程生效的限流口径。 凭据(GWL_USER_ID / GWL_API_KEY)来自环境变量,工具参数里不需要也不能传 userid/apikey。 建议每次会话开始时先调用一次:它同时告诉你上游的读/写/IP 配额,便于安排后续调用节奏。返回 data 含 userid、username、real_level(1~5)、server_time(UTC ISO)、rate_limit{read_per_minute,write_per_minute,ip_per_minute,auth_fail_per_minute}。

Inputs: no named parameters. Returns: object

gwl_remove_from_blacklist解除拉黑B
Idempotent

把一个用户移出组类黑名单(同样会通知对方)。 该用户不在名单里时返回 404;重复调用不幂等。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。

Inputs: cid (required), username (required). Returns: object

gwl_restore_document从回收站恢复A

把软删除的文档从回收站恢复回来。 文档不在回收站 400;无权恢复 403。恢复后返回文档详情(msg=恢复成功)。

Inputs: doc_id (required). Returns: object

gwl_restore_document_revision恢复到某版A

把文档正文恢复到某一版修订(会新写一条修订记录,因此本身可逆)。 需要可编辑权限(403),同样受乐观锁保护:建议带 version。 当前正文已经与该版一致时返回 400(重复调用不幂等)。

Inputs: rev (required), doc_id (required), version. Returns: object

gwl_review_join_request审批加入申请A

批准或拒绝一条加入申请:approve=true 批准入组,false 拒绝。 批准只是建立成员关系,不会因此提权。 已处理过的再审批 409;目标用户在黑名单里 409;申请不存在 404。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。

Inputs: request_id (required), note, approve. Returns: object

gwl_set_object_tags全量替换对象标签A
Idempotent

用给定列表整体替换该对象的标签(不是追加)。 tags=[] 表示清空;超过 8 个或单个超过 24 字返回 400;无权编辑该对象返回 403。 建议先 gwl_get_object_tags 读回现有标签再合并提交,避免误删他人的标签。

Inputs: tags (required), object_id (required), object_type (required). Returns: object

gwl_suggest_tags标签联想A
Read-onlyIdempotent

标签输入联想;q 省略或为空时返回热门标签。 返回 {q, items[{id,name,count}]},count 是该标签被使用的次数。

Inputs: q, limit. Returns: object

gwl_update_document更新文档(乐观锁)A
Idempotent

更新文档:至少要提供一个可变字段(title/content/summary/icon/folder_id/permission_bits/visibility/owning),否则本工具直接报参数错误而不发请求。 并发安全:强烈建议先 gwl_get_document_by_id 拿到 version 并原样传入;版本不符返回 409,且 data 带 current_version / expected_version / editor_username。 base_content 表示「你准备改动的那份原文」,必须与 content 同时提供,服务端据此自动合并他人改动。 重复提交同样内容返回 msg=无变更(幂等)。revision_summary 是这次修订的说明。

Inputs: doc_id (required), icon, title, owning, +8 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 36 tools

    Disambiguation4/5

    Most tools have sharply distinct purposes, and the descriptions explicitly disambiguate dangerous near-pairs (gwl_get_document vs gwl_get_document_by_id, gwl_list_documents vs gwl_list_my_documents, gwl_ping vs gwl_get_me vs gwl_get_permissions). The remaining fuzziness is mild: gwl_list_my_classes, gwl_list_my_orgs and gwl_list_joinable_classes all partly answer "what can I access", and the three tag tools plus gwl_search overlap slightly on discovery.

    Naming Consistency5/5

    Every tool uses the same gwl_ prefix plus snake_case verb_noun construction (get/list/create/update/delete/restore/add/remove/set/join/cancel/review/mark/search/suggest), with no camelCase or stylistic drift. Only gwl_ping lacks a verb, which is a trivial and conventional exception.

    Tool Count3/5

    36 tools is heavy, but the surface genuinely spans several domains (identity/permissions, orgs & groups, join-request workflow, blacklist, documents + revisions, tags, search, notifications). It is still borderline oversized: the document and membership clusters each run ~12 tools and offer obvious consolidation room (e.g. separate list_my_documents / list_documents / list_trash variants).

    Completeness3/5

    Document lifecycle is excellent (create/read/update/soft-delete/restore, revisions and revision restore, trash), and the join-request and blacklist workflows are fully closed-loop. However there are notable holes: no way to list or remove members of a class, no leave_class, and folders are read-only (list_folders only) despite folder_id being required for create_document — agents will dead-end needing a folder they cannot create or manage.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Exposes 30 tools to manage Redmine resources (issues, projects, users, time entries, wiki pages, news, files, roles) via the REST API using stdio transport.
      34
      306 npm
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with the full public ListenBrainz API, exposing 37 tools for listens, stats, playlists, radio, social, and cover art over stdio.
      37
      1
      BSD Zero Clause
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables ZenTao user administration, including token retrieval, user queries, and user creation/update/delete, over stdio or Streamable HTTP transports.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables querying RetroAchievements data — user profiles, unlocks, game progress, game and achievement details, leaderboards, comments, tickets, and site feeds — through 15 read-only, token-efficient tools that cover all documented Web API endpoints over stdio or Streamable HTTP.
      15
      1
      MIT