solucortex-mcp

SoluCortex MCP

适用于 SoluCortex 的官方 Model Context Protocol 服务——为 AI Agent 提供持续更新的技术记忆。

将任何兼容 MCP 的 Agent（Claude Code、Claude Desktop、Cursor、Codex、Cline 等）连接到 你的 SoluCortex 项目，让它在开始工作前回忆重要的决策、约定、风险和架构，并在工作完成后记住所学内容。

网站： solucortex.ai · 设置指南： solucortex.ai/docs/mcp · 工具参考： solucortex.ai/docs/mcp-tools · PyPI： solucortex-mcp · MCP Registry： io.github.soluai-spa/solucortex-mcp

工具

工具	功能	使用时机
solucortex_recall	为任务构建持续更新的上下文（按语义相似度和重要性排序）	任务开始时，在接触代码之前
solucortex_search	对项目记忆进行临时语义搜索	任务进行中有具体问题时
solucortex_remember	记录一条记忆（以 approved 状态存储，并追踪为已授权 Agent）	结束时，或做出相关技术决策时
solucortex_update_memory	修正已有记忆——编辑后会将其状态设为 pending，等待人工在面板中重新批准	记忆的整体意思正确，但细节有误时
solucortex_flag_memory	标记过时或不正确的记忆并说明原因；由人工在面板中处理	记忆需要复核、归档或删除时
solucortex_list_memories	列出记忆，不进行语义搜索	快速查看或审计

治理内建于设计： Agent 提议，人类治理。Agent 无法更改记忆的 status、重写其元数据或删除记忆——编辑后的记忆会回到待处理状态，且只能从 SoluCortex 面板中删除。

要求

• SoluCortex 账户和项目 API 密钥（前缀为 scx_）——可从你的 SoluCortex 控制面板获取。
• 以下任一项：uv（推荐）、Python ≥ 3.10 或 Docker。

配置

stdio 模式（默认，本地）

服务完全通过环境变量配置：

变量	必需	说明
SOLUCORTEX_API_KEY	✅	项目 API 密钥（scx_…）
SOLUCORTEX_PROJECT_ID	可选	默认项目 UUID；若省略，后端会根据 API 密钥推断
SOLUCORTEX_URL	可选	API 基础 URL。默认值为 https://solucortex.ai

HTTP 模式（远程、多租户）

使用 MCP_TRANSPORT=http（或 --http）运行，即可在 $PORT（默认值为 8080）上提供 Streamable HTTP 服务——这是 https://mcp.solucortex.ai 背后的模式。凭据随每个请求发送，并且会忽略环境变量：

请求头	必填	说明
Authorization: Bearer scx_…	✅	调用方的项目 API 密钥（未提供时返回 401）
X-Solucortex-Project	可选	默认项目 UUID；如果省略，后端会根据 API 密钥推断

GET /health（本地还支持 /healthz；Cloud Run 的前端会拦截 /healthz）无需身份验证即可响应。MCP 端点为 /mcp，以无状态方式运行，不会在请求或租户之间共享任何内容。

切勿提交 API 密钥。请将其保存在 MCP 客户端配置的 env 块中，或保存在本地 .env 文件中（参见 .env.example）。

安装

远程（推荐——无需安装）

托管服务 https://mcp.solucortex.ai/mcp 使用 Streamable HTTP；密钥会随每个请求发送：

claude mcp add --transport http solucortex https://mcp.solucortex.ai/mcp \
  --header "Authorization: Bearer scx_xxx" \
  --header "X-Solucortex-Project: your-project-uuid"

也可以在任何支持远程 MCP 的客户端中使用：

{
  "mcpServers": {
    "solucortex": {
      "type": "http",
      "url": "https://mcp.solucortex.ai/mcp",
      "headers": {
        "Authorization": "Bearer scx_xxx",
        "X-Solucortex-Project": "your-project-uuid"
      }
    }
  }
}

Claude Code（本地，stdio）

claude mcp add solucortex \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  -- uvx solucortex-mcp

Claude Desktop / Cursor / Cline（JSON 配置）

将以下内容添加到客户端的 MCP 配置中（claude_desktop_config.json、Cursor 的 mcp.json 等）：

{
  "mcpServers": {
    "solucortex": {
      "command": "uvx",
      "args": ["solucortex-mcp"],
      "env": {
        "SOLUCORTEX_API_KEY": "scx_xxx",
        "SOLUCORTEX_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

从本地克隆安装

git clone https://github.com/soluai-spa/solucortex-mcp
cd solucortex-mcp
cp .env.example .env   # fill in your key
./run.sh               # loads .env, then runs via uv
# or, with SOLUCORTEX_* already exported: uv run solucortex-mcp

Docker

GHCR 上的预构建镜像：

docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  ghcr.io/soluai-spa/solucortex-mcp:latest

也可以自行构建：

docker build -t solucortex-mcp .
docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  solucortex-mcp

该服务通过 stdio 使用 MCP，因此客户端会将其作为子进程启动（-i 会保持 stdin 打开）。

给 Agent 的说明（AGENTS.md）

连接后，也请向 Agent 提供相关方法论：将 templates/AGENTS.md 复制到仓库根目录（可命名为 AGENTS.md 或 CLAUDE.md）。MCP 握手已包含这些说明；此文件可让你将其与代码一起纳入版本控制、添加自己的约定， 还可以选择启用注释掉的 Claude Code hook 配置，以确保 Agent 能随时获取这些说明。

开发

uv sync
uv run solucortex-mcp            # run (stdio)
MCP_TRANSPORT=http uv run solucortex-mcp   # run (HTTP on :8080)
uv run pytest                    # test suite
npx @modelcontextprotocol/inspector uv run solucortex-mcp   # interactive test

注意事项

• Memory 的 type 词汇：规范集合为 architecture, decision, risk, convention, bug_history, tech_debt, sensitive_module, learning, external_integration。某些后端 接受较旧的集合（technical_decision, historical_bug, current_state, task_closure）。 服务会原样传递 type，并返回 HTTP 422，以便你使用另一组类型重试。
• 切勿在 memory 中存储真实机密。请改为记录其位置、类型、严重程度和采取的措施。

许可证

MIT — 详见 LICENSE。