Cortex MCP — Multi-Level Reasoning Server

Cortex MCP

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

概述

Cortex MCP 是一款仅通过 stdio 传输的 MCP 服务，用于执行有状态、深度可控的推理。src/index.ts 中的运行时入口将 createServer() 连接到 StdioServerTransport，而 src/server.ts 中的服务接口则围绕单一的基于会话的推理引擎启用工具、提示词、补全、日志记录和可订阅资源。

Inspector 确认的实时 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 跟踪记录和单条思考文档。
• 通过 completable() 和资源模板补全钩子，为级别、会话 ID 和思考名称提供补全功能。

要求

• 本地使用 npx 或 npm 需要 Node.js >=24。
• 支持 stdio 传输的 MCP 客户端。
• 可选：如果要构建或运行 Dockerfile 定义的容器镜像，则需要 Docker。

快速开始

使用以下标准 MCP 客户端配置：

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

客户端配置

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

使用场景

在合适的深度启动有界推理

当客户端需要以提示词优先的方式开始时，可使用 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 以继续先前的跟踪；如果已有剩余的 thought 输入，则切换到 runMode="run_to_completion"；也可以使用继续和重试提示词来生成下一次调用所需的有效负载。处理程序还支持 rollbackToStep 和 isConclusion，用于修订跟踪或提前结束跟踪。

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

检查实时跟踪，而不重新运行工具

读取 reasoning://sessions 获取活跃会话列表，读取 reasoning://sessions/{sessionId} 获取 JSON 详情视图，读取 reasoning://sessions/{sessionId}/trace 获取 Markdown 记录，或读取 reasoning://sessions/{sessionId}/thoughts/{thoughtName} 获取单个 thought。这样，客户端就可以独立于下一次工具调用来展示进度或审计会话。

相关资源：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 批处理、结构化的观察／假设／评估输入、回滚，以及提前得出结论，同时返回结构化会话状态。

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]

提示词

MCP 能力

工具注解

结构化输出

• reasoning_think 声明了 outputSchema 并返回 structuredContent；当跟踪信息足够小时，还会嵌入跟踪资源。依据：src/tools/reasoning-think.ts:498, src/lib/mcp.ts:97-114。

配置

说明

源代码未定义任何 HTTP 主机/端口配置。其他唯一与环境相关的信号是 Docker 镜像中的 NODE_ENV=production，以及本地 dev:run 脚本中的 --env-file=.env。

安全性

说明

当前源代码未实现身份验证、OAuth、HTTP 来源检查或速率限制控制，因为该服务仅公开 stdio 传输方式。

开发

package.json 中还定义了用于诊断、覆盖率、资源复制和 knip 的辅助脚本。

构建与发布

• .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 发布到 MCP Registry，并将多架构 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。

致谢

贡献与许可证

• 许可证：MIT
• 欢迎通过拉取请求贡献代码。