使用说明

皮质MCP

多级推理MCP服务器，具有可配置的深度级别、基于会话的状态管理、结构化的思维输入和实时跟踪资源。

概述

Cortex MCP是一个仅支持stdio的MCP服务器，用于有状态、深度控制的推理。中的运行时入口点 src/index.ts 连接 createServer() 到 StdioServerTransport，服务器表面 src/server.ts 围绕单个基于会话的推理引擎启用工具、提示、完成、日志记录和可订阅资源。

检查员确认的活动MCP表面是1个工具、6个具体资源、4个资源模板和7个提示。会话存储在内存中，作为MCP资源公开，并在进程重启时清除。

主要特点

reasoning_think 支持分步会话， run_to_completion 批处理、回滚、早期结论和结构化 observation / hypothesis / evaluation 输入。
发动机内置四个深度级别： basic, normal, high，以及 expert，每个都有有限的思维范围和象征性的预算。
及时的助手暴露 reasoning.basic, reasoning.normal, reasoning.high, reasoning.expert, reasoning.continue, reasoning.retry，以及 get-help.
资源端点公开内部文档以及实时会话列表、每个会话的JSON视图、完整的markdown跟踪和单个思想文档。
通过以下方式连接完成级别、会话ID和思想名称 completable() 以及资源模板完成挂钩。

需求

Node.js >=24 用于本地 npx 或 npm 使用。
支持以下功能的MCP客户端 stdio 运输。
可选：如果你想构建或运行由定义的容器映像，请使用Docker Dockerfile.

快速开始

使用此标准MCP客户端配置：

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

客户端配置

Install in VS Code

添加 .vscode/mcp.json:

{
  "servers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

或通过CLI安装：

code --add-mcp '{"name":"cortex-mcp","command":"npx","args":["-y","@j0hanz/cortex-mcp@latest"]}'

有关更多信息，请参阅 VS代码MCP文档.

Install in VS Code Insiders

添加 .vscode/mcp.json:

{
  "servers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

或通过CLI安装：

code-insiders --add-mcp '{"name":"cortex-mcp","command":"npx","args":["-y","@j0hanz/cortex-mcp@latest"]}'

有关更多信息，请参阅 VS代码内部人员MCP文档.

Install in Cursor

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅光标MCP文档.

Install in Visual Studio

添加 mcp.json (VS integrated):

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Visual Studio MCP文档.

Install in Goose

添加 Goose extension registry:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅鹅MCP文件.

Install in LM Studio

添加 LM Studio MCP config:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 LM Studio MCP文档.

Install in Claude Desktop

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅克劳德桌面MCP文档.

Install in Claude Code

添加 Claude Code CLI:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

或通过CLI安装：

claude mcp add cortex-mcp -- npx -y @j0hanz/cortex-mcp@latest

有关更多信息，请参阅克劳德代码MCP文档.

Install in Windsurf

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Windsurf MCP文件.

Install in Amp

添加 Amp MCP config:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

或通过CLI安装：

amp mcp add cortex-mcp -- npx -y @j0hanz/cortex-mcp@latest

有关更多信息，请参阅 Amp MCP文档.

Install in Cline

添加 cline_mcp_settings.json:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅临床MCP文档.

Install in Codex CLI

添加 ~/.codex/config.yaml or codex CLI:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Codex CLI MCP文档.

Install in GitHub Copilot

添加 .vscode/mcp.json:

{
  "servers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 GitHub Copilot MCP文档.

Install in Warp

添加 Warp MCP config:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅扭曲MCP文档.

Install in Kiro

添加 .kiro/settings/mcp.json:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Kiro MCP文件.

Install in Gemini CLI

添加 ~/.gemini/settings.json:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Gemini CLI MCP文档.

Install in Zed

添加 ~/.config/zed/settings.json:

{
  "context_servers": {
    "cortex-mcp": {
      "settings": {
        "command": "npx",
        "args": ["-y", "@j0hanz/cortex-mcp@latest"]
      }
    }
  }
}

有关更多信息，请参阅 Zed MCP文件.

Install in Augment

添加 VS Code settings.json:

添加到您的VS代码 settings.json 在...之下 augment.advanced.

{
  "augment.advanced": {
    "mcpServers": [
      {
        "id": "cortex-mcp",
        "command": "npx",
        "args": ["-y", "@j0hanz/cortex-mcp@latest"]
      }
    ]
  }
}

有关更多信息，请参阅补充MCP文件.

Install in Roo Code

添加 Roo Code MCP settings:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅 Roo代码MCP文档.

Install in Kilo Code

添加 Kilo Code MCP settings:

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

有关更多信息，请参阅基洛代码MCP文档.

用例

从正确的深度开始有限推理

使用 reasoning.basic, reasoning.normal, reasoning.high，或 reasoning.expert 当客户端需要一个提示的第一个入口点或呼叫时 reasoning_think 直接与 query, level，第一个 thought每个响应返回当前会话状态加上一个 summary 告诉客户端如何继续的字符串。

相关工具： reasoning_think
相关提示： reasoning.basic, reasoning.normal, reasoning.high, reasoning.expert

继续、重试或批处理活动会话

重用 sessionId 要继续之前的跟踪，请切换到 runMode="run_to_completion" 当您已经有了剩余的思想输入时，或者使用继续和重试提示来生成下一个调用有效负载。处理程序还支持 rollbackToStep 和 isConclusion 提前修改或结束痕迹。

相关工具： reasoning_think
相关提示： reasoning.continue, reasoning.retry

在不重新运行工具的情况下检查带电痕迹

阅读 reasoning://sessions 对于活动会话列表， reasoning://sessions/{sessionId} 对于JSON详细视图， reasoning://sessions/{sessionId}/trace 获取降价记录，或 reasoning://sessions/{sessionId}/thoughts/{thoughtName} 一个念头。这允许客户端独立于下一次工具调用来显示进度或审核会话。

相关资源： reasoning://sessions, reasoning://sessions/{sessionId}, reasoning://sessions/{sessionId}/trace, reasoning://sessions/{sessionId}/thoughts/{thoughtName}

建筑

[MCP Client]
    |
    | stdio
    v
[src/index.ts]
    createServer()
    -> new StdioServerTransport()
    -> server.connect(transport)
    |
    v
[src/server.ts]
    McpServer("cortex-mcp")
    capabilities:
      - tools
      - prompts
      - completions
      - logging
      - resources { subscribe: true, listChanged: true }
    |
    +--> tools/call
    |     -> reasoning_think
    |     -> src/tools/reasoning-think.ts
    |     -> ReasoningThinkInputSchema / ReasoningThinkToolOutputSchema
    |     -> src/engine/reasoner.ts
    |     -> SessionStore
    |
    +--> prompts/get
    |     -> src/prompts/index.ts
    |
    +--> resources/read
    |     -> src/resources/index.ts
    |     -> internal://* and reasoning://sessions/*
    |
    +--> notifications
          -> logging messages
          -> resources/list_changed
          -> resources/updated
          -> notifications/progress

请求的生命周期

[Client] -- initialize --> [Server]
[Server] -- serverInfo + capabilities --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name: "reasoning_think", arguments} --> [Handler]
[Handler] -- validate args --> [Reasoner + SessionStore]
[Reasoner] -- progress/resource events --> [Server notifications]
[Handler] -- structuredContent + optional trace resource --> [Client]

MCP表面

工具

`reasoning_think`

用于创建和继续多步骤会话的状态推理工具。它支持一步式交互式通话， run_to_completion 批处理、结构化观察/假设/评估输入、回滚和早期结论，同时返回结构化会话状态。

参数	类型	必填	说明
`query`	`string`	无	需要分析的问题或难题。
`level`	`string`	no	深度级别。新会议需要。基本（1-3步，2K预算），正常（4-8步，8K预算），高（10-15步，32K预算），专家（20-25步，128K预算）。
`targetThoughts`	`integer`	no	精确的步数。必须符合级别范围。
`sessionId`	`string`	没有	要继续的会话ID。
`runMode`	`string`	无	“step”（默认）或“run_to_completion”。
`thought`	`any`	否	推理文本。逐字存储。String表示步进模式，String[]表示批处理。
`isConclusion`	`boolean`	否	在最终回答时提前结束会话。
`rollbackToStep`	`integer`	没有可回滚到的基于	0的索引。放弃以后的想法。
`stepSummary`	`string`	否	一句话步骤总结。
`observation`	`string`	否	此步骤的已知事实。
`hypothesis`	`string`	否	提出下一个想法。
`evaluation`	`string`	否	对假设的批判。

Data Flow

1. [Client] -- tools/call {name: "reasoning_think", arguments} --> [Server]
   Transport: stdio
2. [Server] -- dispatch("reasoning_think") --> [Handler: src/tools/reasoning-think.ts]
3. [Handler] -- validate(ReasoningThinkInputSchema) --> [src/engine/reasoner.ts]
4. [Reasoner] -- create/update session --> [src/engine/session-store.ts]
5. [Handler] -- structuredContent + optional embedded trace resource --> [Client]

资源

资源	URI或模板	MIME类型	描述
`server-instructions`	`internal://instructions`	`text/markdown`	MCP服务器的使用说明。
`server-config`	`internal://server-config`	`application/json`	推理服务器的运行时间限制和级别配置。
`tool-catalog`	`internal://tool-catalog`	`text/markdown`	工具参考：模型、参数、输出、数据流。
`tool-info`	`internal://tool-info/{toolName}`	`text/markdown`	根据工具合同详细信息。
`tool-info-reasoning_think`	`internal://tool-info/reasoning_think`	`text/markdown`	合同详细信息 `reasoning_think`.
`workflows`	`internal://workflows`	`text/markdown`	推荐的工作流程和工具顺序。
`reasoning.sessions`	`reasoning://sessions`	application/json	带有摘要的活动推理会话列表。随着会话的进行实时更新。
`reasoning.session`	`reasoning://sessions/{sessionId}`	`application/json`	单个推理会话的详细视图，包括所有想法和元数据。
`reasoning.trace`	`reasoning://sessions/{sessionId}/trace`	`text/markdown`	推理会话的Markdown跟踪（完整内容）。
`reasoning.thought`	`reasoning://sessions/{sessionId}/thoughts/{thoughtName}`	`text/markdown`	单个想法的Markdown内容（例如 `Thought-1`).

提示

提示	参数	描述
`get-help`	none	返回服务器使用说明。
`reasoning.basic`	`query` 必修的， `targetThoughts` 可选	基本深度推理（1-3个想法）。
`reasoning.normal`	`query` 必修的， `targetThoughts` 可选	正常深度推理（4-8个想法）。
`reasoning.high`	`query` 必修的， `targetThoughts` 可选	深度推理（10-15个想法）。
`reasoning.expert`	`query` 必修的， `targetThoughts` 可选	专家深度推理（20-25个想法）。
`reasoning.continue`	`sessionId` 必修的， `query` 可选， `level` 可选	继续现有会话。可选后续查询。
`reasoning.retry`	`query` 必修的， `level` 必修的， `targetThoughts` 可选	使用修改后的参数重试失败的推理任务。

MCP能力

能力	状态	证据
`tools`	已确认	`src/server.ts:203-205`, `src/tools/reasoning-think.ts:479`
`prompts`	已确认	`src/server.ts:205`, `src/prompts/index.ts:201`
`completions`	已确认	`src/server.ts:207`, `src/prompts/index.ts:249`, `src/resources/index.ts:375`
`logging`	已确认	`src/server.ts:204`, `src/server.ts:98`
`resources.subscribe`	已确认	`src/server.ts:208`, `src/server.ts:121`
`resources.listChanged`	已确认	`src/server.ts:208`, `src/server.ts:114`
`progress notifications`	已确认	`src/lib/mcp.ts:71`, `src/tools/reasoning-think.ts:424`

工具注释

注释	价值	证据
`readOnlyHint`	`false`	`src/tools/reasoning-think.ts:500`
`destructiveHint`	`false`	`src/tools/reasoning-think.ts:502`
`openWorldHint`	`false`	`src/tools/reasoning-think.ts:503`
`idempotentHint`	`false`	`src/tools/reasoning-think.ts:501`

结构化输出

reasoning_think 声明 outputSchema 并返回 structuredContent，当跟踪足够小时，使用嵌入式跟踪资源。证据： src/tools/reasoning-think.ts:498, src/lib/mcp.ts:97-114.

配置

变量	默认值	必填	证据
`CORTEX_SESSION_TTL_MS`	`1800000` （30分钟）	否	`src/engine/reasoner.ts:22`, `src/engine/session-store.ts:19`
`CORTEX_MAX_SESSIONS`	`100`	没有	`src/engine/reasoner.ts:23`, `src/engine/session-store.ts:20`
`CORTEX_MAX_TOTAL_TOKENS`	`2000000`	没有	`src/engine/reasoner.ts:24`, `src/engine/session-store.ts:21`
`CORTEX_MAX_ACTIVE_REASONING_TASKS`	`32`	没有	`src/engine/config.ts:41-44`
`CORTEX_REDACT_TRACE_CONTENT`	`false`	没有	`src/engine/config.ts:21`

[！注意] 源未定义任何HTTP主机/端口配置。唯一与环境相关的信号是 NODE_ENV=production 在Docker镜像中 --env-file=.env 在当地 dev:run 脚本。

安全

控制	状态	证据
输入验证	已确认	`src/schemas/inputs.ts:13`, `src/schemas/outputs.ts:46`, `src/prompts/index.ts:207`
stdout安全日志回退	已确认	`src/server.ts:98`, `src/server.ts:145`
仅主线程运行时	已确认	`src/index.ts:15-25`
非根容器用户	已确认	`Dockerfile:37`

[！注意] 当前源中没有实现身份验证、OAuth、HTTP源代码检查或速率限制控制，因为服务器只公开stdio传输。

发展

脚本	命令	目的
`dev`	`tsc --watch --preserveWatchOutput`	在开发过程中查看和编译源代码。
`dev:run`	`node --env-file=.env --watch dist/index.js`	在监视模式下运行内置服务器，并使用可选的本地 `.env` 文件。
`build`	`node scripts/tasks.mjs build`	清洁 `dist`，编译TypeScript，复制资产，并使入口点可执行。
`lint`	`eslint .`	在存储库中运行ESLint。
`type-check`	`node scripts/tasks.mjs type-check`	同时运行源代码和测试TypeScript检查。
`test`	`node scripts/tasks.mjs test`	使用配置的加载器运行TypeScript测试套件。
`test:dist`	`node scripts/tasks.mjs test:dist`	首先进行重建，然后对构建的输出运行测试。
`test:fast`	`node --test --import tsx/esm src/__tests__/*/.test.ts node-tests/*/.test.ts`	在不使用任务包装器的情况下运行快速直接测试命令。
`format`	`prettier --write .`	格式化存储库。
`inspector`	`npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js`	构建服务器并在MCP检查器中打开它。
`prepublishOnly`	`npm run lint && npm run type-check && npm run build`	发布前执行发布检查。

用于诊断、覆盖、资产复制和 knip 定义见 package.json.

构建与发布

.github/workflows/release.yml 凸起 package.json 和 server.json，然后运行 npm run lint, npm run type-check, npm run test，以及 npm run build 在标记和创建GitHub版本之前。
同一工作流使用Trusted Publishing将包发布到npm，使用 mcp-publisher，并将多拱形Docker镜像推送到 ghcr.io.
Dockerfile 使用多级Node 24 Alpine构建，修剪开发依赖关系，并将发布的容器作为 mcp 用户。

故障排除

会话在内存中，默认情况下在30分钟后过期。如果你收到 E_SESSION_NOT_FOUND，开始新会话或增加 CORTEX_SESSION_TTL_MS.
runMode="run_to_completion" 需要足够的 thought 条目以涵盖其余步骤。如果希望服务器在每个步骤后返回，请保持默认值 step 模式。
对于stdio传输，不要在服务器进程周围添加自定义stdout日志。此服务器通过MCP日志路由日志，并回退到 stderr 关于失败。

积分

依赖关系	注册表
@模型上下文协议/sdk	npm
黄道带	npm

贡献和许可

许可证：麻省理工学院
欢迎通过pull请求进行贡献。

使用说明

皮质MCP

概述

主要特点

需求

快速开始

客户端配置

用例

从正确的深度开始有限推理

继续、重试或批处理活动会话

在不重新运行工具的情况下检查带电痕迹

建筑

请求的生命周期

MCP表面

工具

reasoning_think

资源

提示

MCP能力

工具注释

结构化输出

配置

安全

发展

构建与发布

故障排除

积分

贡献和许可

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH MCP服务器

`reasoning_think`