返回首页

数字核心 · MCP 服务器

机器栖居于句法

DWFW 核心包含一个 MCP（Model Context Protocol）服务器，让智能体——Claude 或任何 MCP 客户端——读取观察站、图谱和 Event Stack，并以机器出处提出连接。它不能确认连接、赋予意义或推进环节：这是服务账号的 RBAC 所禁止的，而不是靠智能体的自觉。

服务器 https://dwfw.trabemflex.com/mcp · OAuth · stdioAPI 指南代码与说明 · GitHub

01

这是什么

MCP（Model Context Protocol）是让语言模型连接外部工具的开放协议。dwfw 服务器有两种传输方式，共用同一套逻辑：本地开发用 stdio（mcp/index.mjs），生产环境用 Streamable HTTP，位于 https://dwfw.trabemflex.com/mcp。二者都把智能体的每次调用翻译成对核心 REST API 的请求——与 API 指南所记录的是同一个 API，权限也相同。

角色分工出于准则：机器栖居于句法，人类栖居于语义。接入的智能体可以发现形式规律并提出连接；由人类策展人在面板中确认或放弃。服务器不授予任何权力：决定权在核心的 RBAC，通过 investigador 角色的服务账号行使。

现在接入的智能体能做什么：搜索并读取作品、作者与节点，浏览图谱，查阅 Event Stack 日程，并在作品与节点之间提出连接（以"提议"状态、出处为机器进入）。不能做什么：确认这些提议、赋予意义、推进策展运动，或查看和操作用户、凭证及私有资产。推荐的连接方式是一键 OAuth 2.1（与 HubSpot、Slack 连接器相同）：在授权页面用你的 DWFW 用户确认后，客户端即完成连接，无需复制令牌；每个会话归属于一个人，出现在审计日志中，会自动过期，并可在后台吊销。对于不支持 OAuth 的客户端，仍保留基于令牌的备选方式。

02

一键连接（OAuth）

推荐方式。服务器实现了 OAuth 2.1，支持客户端动态注册与 PKCE——与 HubSpot、Slack 连接器相同的流程：你在授权页面用自己的 DWFW 用户确认后，客户端即完成连接，无需手动复制令牌。每个会话都归属于一个人（审计日志记录其邮箱），可在后台（MCP 会话）吊销，也会自动过期：访问令牌 1 小时，客户端最长可续期 30 天。

  • claude.ai（网页或桌面版）：设置 → 连接器 → "添加自定义连接器" → URL https://dwfw.trabemflex.com/mcp → 在 DWFW 页面上授权。
  • Claude Code：使用下方命令；浏览器会打开授权页面，确认后会话即连接。
# Claude Code：无需令牌或请求头——浏览器会打开 DWFW 的授权页面
claude mcp add --transport http dwfw https://dwfw.trabemflex.com/mcp

# 授权后应显示 ✔ Connected
claude mcp list

03

使用令牌的远程连接（备选）

生产传输为 Streamable HTTP，且是无状态的：每个请求自包含，没有会话，也不需要客户端亲和。如果无法使用 OAuth，手动的备选方式是客户端令牌（见下一节）；令牌只在 Authorization 请求头中传输，绝不放在 URL 里。

# Claude Code：连接远程服务器（令牌见下一节）
claude mcp add --transport http dwfw https://dwfw.trabemflex.com/mcp \
  --header "Authorization: Bearer dwfw_mcp_…"

# 检查服务状态（无需凭证）
curl https://dwfw.trabemflex.com/mcp/salud

# 其他支持远程 HTTP 的 MCP 客户端：通用配置
{
  "mcpServers": {
    "dwfw": {
      "url": "https://dwfw.trabemflex.com/mcp",
      "headers": { "Authorization": "Bearer dwfw_mcp_…" }
    }
  }
}

04

远程认证

客户端令牌（dwfw_mcp_…）通过管理层会话调用 API 签发：POST https://dwfw.trabemflex.com/api/tokens-mcp，请求体为 {"nombre": "使用者名称"}。令牌明文仅出现在该 JSON 响应中——请当场复制；数据库只保存其哈希，之后无法再读取。在后台取消勾选"启用"即吊销（≤1 分钟内生效）；可选的到期时间会让它自动失效。

三个身份互不混淆：令牌标识远程客户端；MCP 服务器以 maquina@dwfw.test 的身份、用一把绝不离开服务器的内部密钥访问 API；权限由该用户的 RBAC 决定。OAuth 会话与这些令牌并存：同一传输、同一工具、同一 RBAC 屏障。

05

本地连接（stdio）

需要 Node 18+ 和一份仓库副本。服务器不需要数据库或本地配置：只需指向 API 的环境变量。在 Claude Desktop 中，把下面的 JSON 块加入 claude_desktop_config.json。

# 克隆核心仓库并安装服务器依赖（Node 18+）
git clone https://github.com/juanceldran/dwfw-core
cd dwfw-core/mcp && pnpm install --ignore-workspace

# 手动启动（通过 stdio 通信；通常由 MCP 客户端启动）
DWFW_API_URL=https://dwfw.trabemflex.com/api DWFW_API_KEY=… node index.mjs
# Claude Code：注册服务器（把路径改成你本地仓库的位置）
claude mcp add dwfw \
  -e DWFW_API_URL=https://dwfw.trabemflex.com/api \
  -e DWFW_API_KEY=… \
  -- node /ruta/dwfw-core/mcp/index.mjs

# 确认它出现并已连接
claude mcp list
{
  "mcpServers": {
    "dwfw": {
      "command": "node",
      "args": ["/ruta/dwfw-core/mcp/index.mjs"],
      "env": {
        "DWFW_API_URL": "https://dwfw.trabemflex.com/api",
        "DWFW_API_KEY": "…"
      }
    }
  }
}

06

凭证与环境变量

推荐方式是服务账号 maquina@dwfw.test（investigador 角色）的 API 密钥：在后台该用户的档案中勾选 "Enable API Key" 生成。它以 Authorization: usuarios API-Key … 请求头传输，避免在客户端配置中保存密码。备选方式是 DWFW_EMAIL + DWFW_PASSWORD（服务器会自动续期 JWT）。

没有凭证时，服务器以公开只读模式运行：档案（环节 7 的作品）、作者、节点、图谱、意义以及 Event Stack 节目单。提出连接需要服务会话。

# 核心 API（生产环境；开发环境为 http://localhost:3000/api）
DWFW_API_URL=https://dwfw.trabemflex.com/api

# 服务账号的 API 密钥（推荐；在后台生成）
DWFW_API_KEY=…

# 备选：使用服务账号的邮箱和密码登录
DWFW_EMAIL=maquina@dwfw.test
DWFW_PASSWORD=…

# 响应的默认语言：es · en · zh · ja
DWFW_LOCALE=es

07

工具

六个读取工具和唯一一个写入工具。名称和参数是技术标识符，不翻译；内容则按 locale 以所请求的语言返回。

工具作用参数
buscar_obras · 读取服务会话可见的观察站作品；按文本、环节或类型筛选。q · movimiento · tipo · limit · locale
ficha_obra · 读取作品的完整档案：作者、连接（起点与终点）以及已赋予的意义。id · locale
buscar_autores · 读取设计师、团体、实验室与机构（第二层）。q · tipo · locale
buscar_nodos · 读取图谱的节点（第三层）：思潮、既有技术发展、社群、机构、文化张力。q · tipo · locale
cartografia · 读取图谱的连接；默认返回全部，也可按状态筛选（propuesta · confirmada · descartada）。estado · locale
programa · 读取Event Stack 的节目单：各届、品牌章节与视听作品。locale
proponer_conexion · 写入唯一的写入：创建一条机器出处、提议状态的连接，并在 nota 中给出证据。origen · destino · tipoRelacion · nota

dwfw://doctrina — 只读资源，以 markdown 提供核心的硬性规则。客户端可以在智能体开始工作前将其载入上下文。

08

能做什么，不能做什么

这些界限不是智能体的承诺：核心服务器在每次请求时强制执行。服务账号拥有读取能力和 conexion:proponer；任何其他写入都会收到 403 及明确信息。即使智能体尝试，核心也会阻止。

可以

  • ● 读取完整的观察站（任意环节的作品）、作者、节点、连接、意义以及 Event Stack 节目单。
  • ● 按文本、类型、环节或状态搜索和筛选，支持四种语言（locale）。
  • ● 在作品与/或节点之间提出连接（起点与终点可任意组合），并在 nota 中给出句法证据：它们以 maquina 出处、propuesta 状态诞生。
  • ● 读取 dwfw://doctrina 资源，在行动前了解规则。

不可以

  • ● 确认或放弃连接：这是语义行为，需要 conexion:confirmar 能力（返回 403 并附明确信息）。
  • ● 赋予意义（第四层）：需要 significado:asignar 能力，仅保留给人类策展人（403）；此外服务器对每个意义强制 procedencia: humano。
  • ● 推进策展环节：作品的状态只能通过 movimiento:avanzar 改变。
  • ● 创建、编辑或删除作品、作者、节点、届次或用户；也不能上传或发布 Media 资产。
  • ● 请求或推断人气指标：API 中不存在点赞、浏览量或排名（算法悬置）。
# 提出一个连接：以"提议"状态诞生，出处为机器
proponer_conexion {
  "origen":  { "tipo": "obras", "id": 3 },
  "destino": { "tipo": "nodos", "id": 2 },
  "tipoRelacion": "dialoga_con",
  "nota": "两者都在处理模拟的生物生长：菌丝体作为生成逻辑。"
}
# → { "ok": true, "id": 12, "estado": "propuesta", "procedencia": "maquina",
#     "mensaje": "Propuesta registrada. Queda pendiente de confirmación humana." }

# 查看等待人工确认的提议
cartografia { "estado": "propuesta" }

09

协议版本

HTTP 传输提供官方 SDK 支持的协议修订：2025-11-25、2025-06-18、2025-03-26 和 2024-11-05。使用 2026-07-28 修订（它让协议变为无状态——本服务器已然如此）的客户端会自行探测并向下协商（新版 Claude Code 就是这样）。等 SDK 发布该修订后，采用它只是升级一个依赖，而非重新设计。

10

面向智能体的准则

开始工作前，智能体应载入 dwfw://doctrina 资源。简而言之：

  • 每一层都有出处：机器提出的内容在人类确认之前始终是提议。
  • 算法悬置：顺序由思想的分量决定；没有可优化或可索取的指标。
  • 七个环节：只有人类能推进策展状态；作品之中，只有环节 7（档案）无需会话即可公开。
  • 文化起源是描述性数据，绝不是排序或等级的标准。
  • 技术资产在到达环节 7 之前保持私密（盲评策展）。
每一层都有出处 · 算法悬置 · 七个环节