GWL MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GWL MCP Server list my recent documents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 的区别
维度 |
|
|
协议实现 | 纯标准库手写 JSON-RPC | 官方 |
传输 | stdio + 极简 HTTP | stdio + Streamable HTTP + 旧版 SSE(双端点) |
参数校验 | 手写检查 | Pydantic 注解 → |
结构化输出 | 无 |
|
资源 | 无 | 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 也照它渲染)。
变量 | 默认 | 说明 |
| — | 必填。数字用户 id |
| — | 必填。 |
|
| 上游基址;本地联调改 |
|
| 上游基址是 |
| 空 | 3 位组类 id,作为 |
|
| 单次上游请求超时(秒,1~120) |
|
| 单次工具调用(含全部重试与退避)的总墙钟预算(秒,5~300,且 ≥ |
|
| 额外重试次数(0~5),见 §7 重试策略 |
|
|
|
|
|
|
| 空 | 指向一个 |
|
| 只影响 http/sse 传输 |
|
| 0~65535;填 0 表示让系统挑端口 |
|
| Streamable HTTP 路径(sse 固定 |
| 空 | 保护 MCP 端点本身的令牌(不是 GWL apikey),≥16 字符 |
| 内置回环 + Inspector | 额外允许的浏览器 Origin,逗号分隔(SDK 精确匹配,端口要写全) |
|
| 会话空闲回收(秒,60~86400) |
|
| 请求体上限(MB,1~64) |
|
|
|
|
| 明知风险时允许「非回环绑定 + 不设令牌」(不推荐) |
绑非回环地址(如
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 stdiostdout 只有 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( | stdio | |
Claude Code(项目 | stdio | |
Cursor( | stdio | |
VS Code / GitHub Copilot( | stdio | |
Cline( | stdio | |
Continue( | stdio | |
Windsurf( | stdio | |
任何支持 Streamable HTTP + 自定义头的客户端 | http | |
直接连线上托管 | http | |
只认 stdio 但想连远程的客户端 | stdio→http 桥 | |
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 | 内容 | 是否打上游 |
| 基址、鉴权方式、限流口径、超时/重试策略、写保护状态(不含任何密钥) | 否 |
| 工具 ↔ HTTP 端点对照表(含只读/幂等/参数名) | 否 |
| 当前 userid 的资料 | 是 |
| 实时权限快照 | 是 |
| 未读通知摘要 | 是 |
| 按 id 读文档(模板资源) | 是 |
| 按 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.md10. 验收记录(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 的代码事实;以下需要产品/上游确认:
POST /documents非幂等(重复调用会多一篇)。当前只在描述里提醒、idempotentHint=false, 没有做客户端幂等键;上游若支持 Idempotency-Key 可以再补一层。GET /documents/trash的分页口径按代码同样是 page/size,上游文档未明写。限流是进程内滑窗(多进程/多机部署会翻倍),所以本服务把 429 当作可重试信号而不是硬失败。
上游没有匿名健康检查端点,
--check借用GET /ping(会消耗一次读额度)。X-Org-Class只是「以某组类身份发请求」,判定仍在上游;本服务不做任何本地提权假设。MCP 的 logging 能力已被规范弃用(SEP-2577),因此不使用
ctx.log(),可观测性依赖 stderr 日志。未封装 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 stdio14. 上游接口变了怎么同步
改/加
site-back/routes/api_v1.py的路由;在
gwl_mcp/tools/<域>.py增删工具(endpoint 写清方法 + 路径模板);更新
tests/test_tools_contract.py的 EXPECTED_TOOLS / EXPECTED_ENDPOINTS;python scripts/write_inventory.py重新生成docs/API-INVENTORY.md;python -m pytest全绿,并同步本 README §6 工具表(可直接从 tools/list 导出)。
Available Tools
36 toolsgwl_add_to_blacklist拉黑用户A
把一个用户加入组类黑名单(会同时给对方发一条站内通知)。 拉黑自己 400;已在名单里 409。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。
Inputs: cid (required), username (required), reason. Returns: object
gwl_cancel_join_request撤回我的申请ADestructiveIdempotent
撤回我自己提交的加入申请,状态变为 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删除文档(软删除)ADestructiveIdempotent
把文档移入回收站(软删除,可用 gwl_restore_document 恢复)。 仅作者或被授权者,否则 403;已经是回收站状态则 404。 不可恢复的永久删除接口本服务刻意不提供。
Inputs: doc_id (required). Returns: object
gwl_get_class组类详情ARead-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 读文档ARead-only
按 slug 读取文档全文(返回字段随可见性做权限位掩码)。 ⚠️ 有副作用:每次命中都会 view_count + 1,因此标记为非幂等。 只是要读内容做编辑时,请改用 gwl_get_document_by_id(不加浏览数)。 不存在 404;无权查看 403。
Inputs: slug (required). Returns: object
gwl_get_document_by_id按 id 读文档ARead-onlyIdempotent
按文档 id 读取全文,不增加浏览数,是编辑前的推荐读法。 返回里的 version 就是乐观锁基线,更新时原样带回 data.version。 软删除的文档只有作者或超管能看到,其他人 404。
Inputs: doc_id (required). Returns: object
gwl_get_document_revision某版修订全文ARead-onlyIdempotent
读取某一版修订的全文,并带 current_version 与 can_restore。 该修订不存在 404;没有内容快照 404。
Inputs: rev (required), doc_id (required). Returns: object
gwl_get_join_info组的加入状态ARead-onlyIdempotent
查询某组类的可见性与「我」的状态:is_public、joinable、is_member、blacklisted、request(我提交的待处理申请,没有则 null)。 这条不需要组类身份,任何人都能先探测再决定要不要申请加入。
Inputs: cid (required). Returns: object
gwl_get_me我的资料ARead-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读对象标签ARead-onlyIdempotent
读取某个对象当前的标签(裸数组 [{id,name}],按名称排序)。 能看到对象就能看到标签;看不到对象 404 / 403。 object_id 用字符串:文档传 doc_id,组织/组传 3 位 cid,发现条目传条目 id。
Inputs: object_id (required), object_type (required). Returns: object
gwl_get_permissions实时权限快照ARead-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标签聚合ARead-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组类黑名单ARead-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组收到的申请ARead-onlyIdempotent
列出某组类收到的加入申请(裸数组,需管理权限)。 传组织 id 会汇总其下辖组的申请。status 默认 pending,可取 all / approved / rejected。需要该组类的管理角色(class_role=owner 或权限含 manage),否则 403。
Inputs: cid (required), status. Returns: object
gwl_list_document_revisions修订历史ARead-onlyIdempotent
列出文档的修订历史(裸数组:revision_num、editor_username、summary、has_content、created_at)。 不含正文;取某一版全文用 gwl_get_document_revision。
Inputs: doc_id (required). Returns: object
gwl_list_documents文档列表(分页)ARead-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文件夹列表ARead-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可加入的公开组ARead-onlyIdempotent
列出所有允许自助加入的 public 组(返回裸数组,上限 200 条)。 class_id 可收窄到某个组织下的组;传了不属于任何组织的 id 会 400。
Inputs: class_id. Returns: object
gwl_list_my_classes我的组类清单ARead-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我的文档ARead-onlyIdempotent
列出我自己的未删除文档(分页包络)。 folder_id 默认 0(只看根目录);要一次看全部请传 -1。
Inputs: page, size, folder_id. Returns: object
gwl_list_my_join_requests我提交的申请ARead-onlyIdempotent
列出我提交过的加入申请(裸数组)。默认只返回待处理(pending)的; handled=true 时连已批准/已拒绝/已撤回的一起返回。 每项含 group、requester_username、reviewer_username、status、already_member。
Inputs: handled. Returns: object
gwl_list_my_orgs我的组织树ARead-onlyIdempotent
返回我加入/拥有的组织,组织为顶层、下辖我可见的组(groups 数组)。 适合先看清层级关系,再决定用哪个 cid 去调用组类详情或黑名单类工具。
Inputs: no named parameters. Returns: object
gwl_list_notifications我的通知ARead-onlyIdempotent
返回我的站内通知 + 我当前可见的全局通知 + 未读计数。 结构:{personal[], global[](带 is_read), unread{total,global,personal}}。 这不是分页包络,用 limit 截断(默认 100,最大 200)。
Inputs: limit. Returns: object
gwl_list_trash我的回收站ARead-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连通性与凭据自检ARead-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解除拉黑BIdempotent
把一个用户移出组类黑名单(同样会通知对方)。 该用户不在名单里时返回 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_search标题搜索ARead-onlyIdempotent
按标题跨对象搜索(文档 / 组织 / 组 / 发现条目),逐条判权后分页返回。 data 里除分页包络外还有 q、types[]、counts{document,organization,group,discover},items 每项含 type、id、title、summary、icon、url、matched 与范围字段。 types 可多值;传 discover_item 会被映射成上游的 discover。 q 必填且不超过 64 个字符,否则 400。命中量超过扫描上限时返回 scan_truncated=true。
Inputs: q (required), page, size, tags, +3 more. Returns: object
gwl_set_object_tags全量替换对象标签AIdempotent
用给定列表整体替换该对象的标签(不是追加)。 tags=[] 表示清空;超过 8 个或单个超过 24 字返回 400;无权编辑该对象返回 403。 建议先 gwl_get_object_tags 读回现有标签再合并提交,避免误删他人的标签。
Inputs: tags (required), object_id (required), object_type (required). Returns: object
gwl_suggest_tags标签联想ARead-onlyIdempotent
标签输入联想;q 省略或为空时返回热门标签。 返回 {q, items[{id,name,count}]},count 是该标签被使用的次数。
Inputs: q, limit. Returns: object
gwl_update_document更新文档(乐观锁)AIdempotent
更新文档:至少要提供一个可变字段(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
Scored across 36 tools
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.
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.
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).
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
Related MCP Connectors
Caelara Labs Document Utilities tools over remote MCP. Calls need an X-Caelara-Key API key.
Read, search and edit owned AppStruct documents using scoped API keys.
US government data as clean JSON for AI agents: SAM.gov contract opportunities, USAspending awards, Grants.gov grants, House STOCK Act trades, and SEC EDGAR filings (Form 4 insider trades, 8-K events, 13F holdings, 13D/G stakes, XBRL fundamentals, 10-K/10-Q sections). 19 read-only tools. Data is as fresh as each source publishes; congressional trades lag up to 45 days and report dollar ranges (House only). Free tier, no card.
Hosted NeuroDock — stateless communication and planning tools over OAuth-secured Streamable HTTP.
Related MCP Servers
- AlicenseBqualityBmaintenanceExposes 30 tools to manage Redmine resources (issues, projects, users, time entries, wiki pages, news, files, roles) via the REST API using stdio transport.34306 npm7MIT
- AlicenseAqualityDmaintenanceEnables interaction with the full public ListenBrainz API, exposing 37 tools for listens, stats, playlists, radio, social, and cover art over stdio.371BSD Zero Clause
- FlicenseNot gradedqualityCmaintenanceEnables ZenTao user administration, including token retrieval, user queries, and user creation/update/delete, over stdio or Streamable HTTP transports.-
- AlicenseBqualityBmaintenanceEnables 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.151MIT