NeuroDock (hosted)

neurodock-remote

NeuroDock 的组合式远程 MCP 服务（ADR 0008 / ADR 0009，Phase 2）。

它将三个无状态的 NeuroDock 服务组合到一个 Streamable HTTP 端点中，并且仅 公开适用于远程的工具：

源服务	远程公开的工具
mcp-translation	translate_incoming、check_tone、rewrite_outgoing、brief_meeting
mcp-guardrail	check_rumination、check_hyperfocus、check_sycophancy
mcp-task-fractionator	仅 decompose

自愿启用的存储功能（ADR 0010 Phase C/D）

四个认知图谱工具（recall_entity、record_fact、 recall_decisions、weekly_rollup）也会公开，但受限使用：调用者必须 登录账户并且明确启用存储。两种模式并存；每位用户始终只处于其中一种模式：

工具	模式	功能
enable_hosted_storage	hosted	NeuroDock 为每位用户配置一个专属的 Turso 数据库，并在其中存储事实。返回同意披露信息。
connect_byos_storage	byos	你提供自己的 libSQL/Turso 数据库；NeuroDock 仅存储连接信息。
disable_and_erase_storage	→ none	Hosted：销毁你的 Turso 数据库。BYOS：清除已存储的连接信息（不触碰你的数据库）。无论哪种方式，都会清除偏好设置/同意状态。
disconnect_storage	→ none	仅适用于 BYOS 的别名：清除连接信息和偏好设置。（要清除 hosted 存储，请使用 disable_and_erase_storage。）
storage_status	—	报告你的模式（hosted | byos | none）。

系统根据用户记录的存储偏好选择模式；统一的解析器会将每次认知图谱调用路由到 hosted 或 BYOS 后端。与 Phase D 相比，隐私边界没有变化：匿名或未提供令牌的调用者会收到 STORAGE_NOT_AVAILABLE，并且不会存储、读取或配置任何内容；已登录但未启用存储的调用者会收到 STORAGE_NOT_CONNECTED。

Hosted 需要已配置的 Turso 组织/组/令牌。 设置 NEURODOCK_TURSO_PLATFORM_TOKEN + NEURODOCK_TURSO_ORG（+ 可选的 NEURODOCK_TURSO_GROUP，默认为 default，且该组必须已存在于该组织中）。 未设置这些变量时，系统会拒绝 enable_hosted_storage，并且只提供 BYOS。

加密密钥的保管（坦诚说明局限）。 BYOS 身份验证令牌和 hosted Turso 数据库令牌在静态存储时，均使用由单一运维方持有的 NEURODOCK_STATE_MASTER_KEY 加密。这意味着 NeuroDock _在技术上可以_解密已存储的 令牌。这是 ADR 0010 中记录的待解决问题；后续工作将采用每用户密钥/信封密钥（使运维方无法单方面读取用户的数据库令牌）。 无论采用哪种方案，磁盘上的格式都保持不变，因此未来的方案可以重新封装密钥，而无需迁移数据。

刻意不包含的内容

Chronometric 会话状态、用户配置文件（神经类型数据）以及 task-fractionator 的 next_one（读取本地图谱）绝不会挂载。它们保存本地状态，严格限定在本地 stdio 安装中。此边界由代码强制执行，并通过针对 REMOTE_TOOL_NAMES 的测试加以锁定。

这是一个部署产物，不是已发布的软件包——它不会上传到 PyPI（通过 @neurodock/cli 进行本地安装的方式保持不变）。与之前完全相同，本地专用工具仍可通过 stdio 服务使用。

技能交付（托管／远程用户）

远程服务提供的是工具，不是技能。技能是客户端在本地读取的 Markdown，因此远程端点不会交付它们。托管／远程用户获取各神经类型技能的方式与本地用户相同：安装 Claude Code marketplace 插件（其中包含这些技能），或通过 @neurodock/cli 运行 neurodock install-skills，将每项技能复制到 ~/.claude/skills/neurodock-<name>/SKILL.md，供 Claude Code／Claude Desktop 使用。交付方式请参阅 packages/skills/README.md。

在本地运行

# from the repo root
uv run --package neurodock-remote neurodock-remote
# serves http://127.0.0.1:8000/mcp  (+ /health)

使用 MCP Inspector 检查，并将其指向 http://127.0.0.1:8000/mcp。

配置

环境变量	默认值	用途
NEURODOCK_HTTP_HOST	127.0.0.1	绑定主机（容器中为 0.0.0.0）。
NEURODOCK_HTTP_PORT	8000	绑定端口。
NEURODOCK_AUTH_PROVIDER	none	none | clerk | workos | jwt。托管部署使用 clerk。
NEURODOCK_PUBLIC_URL	—	公共基础 URL，例如 https://mcp.neurodock.org（clerk/workos/jwt 必需）。
NEURODOCK_OAUTH_REQUIRED_SCOPES	—	可选，以逗号分隔。
NEURODOCK_CLERK_DOMAIN	—	clerk：你的 Clerk 实例域名（例如 your-app.clerk.accounts.dev）。
NEURODOCK_CLERK_CLIENT_ID	—	clerk：OAuth 应用客户端 ID。
NEURODOCK_CLERK_CLIENT_SECRET	—	clerk：OAuth 客户端密钥（请将其设为密钥，而非明文）。
NEURODOCK_CLERK_SECRET_KEY	—	存储（ADR 0010 C/D）：Clerk Backend API 密钥；用于持久化每位用户的存储指针。
NEURODOCK_STATE_MASTER_KEY	—	存储（ADR 0010 C/D）：用于静态加密 BYOS/托管数据库令牌的主密钥。
NEURODOCK_TURSO_PLATFORM_TOKEN	—	托管（ADR 0010 C）：Turso Platform API 令牌；用于创建和销毁每位用户的数据库。
NEURODOCK_TURSO_ORG	—	托管（ADR 0010 C）：创建托管数据库的 Turso 组织标识。
NEURODOCK_TURSO_GROUP	default	托管（ADR 0010 C）：创建托管数据库的 Turso 组（必须已存在）。
NEURODOCK_GRAPH_DISABLE_EMBEDDINGS	1（镜像）	存储：保持托管图精简（不使用 fastembed）。在 Dockerfile 中设置。
NEURODOCK_AUTHKIT_DOMAIN	—	workos：你的 AuthKit 域名。
NEURODOCK_OAUTH_ISSUER / _JWKS_URI / _AUDIENCE	—	jwt：通用 OIDC 资源服务配置。

⚠️ 对外公开前必须启用身份验证。 如果未设置 NEURODOCK_AUTH_PROVIDER， 服务端将以未进行身份验证的状态运行，并输出醒目警告——此模式 仅用于 localhost/集成测试（ADR 0009 §3）。身份提供商是配置选项，而非代码变更；FastMCP 原生支持 Clerk、WorkOS AuthKit 和 Auth0 提供商，并支持此处接入的通用 JWT 验证器。

容器（任意主机）

# build from the repo root (the Dockerfile uses root-relative COPY paths)
docker build -f packages/remote/Dockerfile -t neurodock-remote .
docker run --rm -p 8000:8000 \
  -e NEURODOCK_AUTH_PROVIDER=clerk \
  -e NEURODOCK_CLERK_DOMAIN=your-app.clerk.accounts.dev \
  -e NEURODOCK_CLERK_CLIENT_ID=xxxx \
  -e NEURODOCK_CLERK_CLIENT_SECRET=yyyy \
  -e NEURODOCK_PUBLIC_URL=https://mcp.neurodock.org \
  neurodock-remote

部署到 Cloudflare Containers

选定的托管平台（ADR 0009）。Python 容器运行在 Cloudflare Containers 上，前面由一个轻量 Worker (worker/index.ts) 提供服务，并负责 mcp.neurodock.org 自定义域名。配置见 wrangler.jsonc。

需要 Workers Paid 计划——Containers 不在免费套餐中。 Worker 和容器仅用于部署；此目录有意不作为 pnpm-workspace 成员，因此安装和部署都直接在此处进行。

1. 创建 Clerk OAuth 应用，并记下实例域名和客户端 ID/密钥。

2. 在 wrangler.jsonc 中填写 vars（NEURODOCK_CLERK_DOMAIN、 NEURODOCK_CLERK_CLIENT_ID）——这些不是密钥。

3. 在此目录（packages/remote/）中：

   npm install
   npx wrangler secret put NEURODOCK_CLERK_CLIENT_SECRET   # paste the secret
   # Optional — enable the opt-in memory tools (ADR 0010 C/D). Without the next
   # two the tools stay visible but un-backed (sign-in/enable refusal):
   npx wrangler secret put NEURODOCK_CLERK_SECRET_KEY      # Clerk Backend API key
   npx wrangler secret put NEURODOCK_STATE_MASTER_KEY      # token-encryption master key
   # Optional — enable NeuroDock-hosted storage (ADR 0010 C). Also set
   # NEURODOCK_TURSO_ORG (and NEURODOCK_TURSO_GROUP) in wrangler.jsonc `vars`.
   # Without the token + org, enable_hosted_storage is refused; BYOS still works:
   npx wrangler secret put NEURODOCK_TURSO_PLATFORM_TOKEN  # Turso Platform API token
   npx wrangler deploy                                     # builds ../Dockerfile, pushes, deploys
   

   wrangler deploy 会构建镜像（上下文 ../../ = 仓库根目录）、自动配置 mcp.neurodock.org DNS 和 TLS（通过 custom_domain 路由），并在 Worker 后启动容器。

4. 验证：访问 https://mcp.neurodock.org/health，确认返回 200，然后在 Claude 中添加 https://mcp.neurodock.org/mcp 作为自定义连接器，并完成 Clerk OAuth 往返流程。

有关传输方式、范围、身份验证和托管平台的决策，请参阅 ADR 0009。

状态： 此 Cloudflare 部署配置是已根据文档验证的脚手架；尚未实际运行 wrangler deploy。首次部署即为验证步骤。