科特克斯-MCP

Name: 科特克斯-MCP
Author: effatico

作者：effatico4 星标更新：2025-11-03

安装使用来源：spider==github.com

项目介绍

Kortx

快速开始 • 文档 • 示例 • 贡献指南

Kortx 是一个轻量级的模型上下文协议 (MCP) 服务器，它赋予编程助手访问以下内容的能力：

OpenAI GPT-5 模型（gpt-5，gpt-5-mini，gpt-5-nano，gpt-5-codex）并具有自动回退功能。
Perplexity Sonar 模型用于实时研究。
GPT 图像（gpt-image-1）用于视觉生成和编辑。
默认的上下文收集器可以摄取本地文件摘录，并且当运行时可选地连接到 Serena，MCP 知识图谱，以及 CCLSP MCP 服务器。

该服务器附带结构化日志记录、请求速率限制、响应缓存，以及一个以非root用户身份运行的强化Docker构建。目前传输仅支持标准I/O（尚未实现HTTP）。

高亮功能

六种咨询工具加上批量运行器，覆盖规划、替代方案、文本改进、调试、研究和图像工作流程。
开箱即用的基于文件的上下文丰富功能，带有可插拔的MCP连接器，准备在可用时连接到 Serena/MCP 知识图谱/CCLSP。
Perplexity 集成（需要API密钥）用于引用支持的答案和图像搜索。
可配置的OpenAI模型、推理努力程度、详细程度和重试行为。
内置的速率限制、缓存和可选审计日志，以避免淹没上游API。
Dockerfile使用多阶段构建、npm审核，并以UID/GID 1001运行。

快速开始

设置凭证（当前配置需要两个密钥）：

export OPENAI_API_KEY=sk-your-openai-key
export PERPLEXITY_API_KEY=pplx-your-perplexity-key

将Kortx添加到您的MCP客户端。示例通用配置：

{
  "mcpServers": {
    "kortx-mcp": {
      "command": "npx",
      "args": ["-y", "@effatico/kortx-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}"
      }
    }
  }
}

针对Claude Code、VS Code Copilot、Cursor等客户端的具体步骤可在 docs/integration 下找到。

工具概述

think-about-plan – 结构化的计划审查，包括优势、风险和后续问题。
suggest-alternative – 生成可行的替代方案及其权衡和约束。
improve-copy – 改进技术文案，提供语气、清晰度和可访问性指导。
solve-problem – 调试助手，涵盖根本原因分析和补救措施。
search-content – 基于Perplexity的网络/学术/SEC搜索，附带引用和可选图像。
create-visual – 基于GPT图像的生成器/编辑器；搜索模式复用Perplexity进行视觉灵感。
batch-consult – 并行运行多个工具调用，并返回聚合结果。

每个咨询工具都接受一个可选的 preferredModel。OpenAI客户端在失败时会自动通过 gpt-5 → gpt-5-mini → gpt-5-nano 回退。

配置要点

最小环境变量：

OPENAI_API_KEY – 必需
PERPLEXITY_API_KEY – 必需（如果您没有密钥，可以通过省略 search-content / create-visual 搜索模式来禁用Perplexity集成）

常见覆盖项（参见 .env.example 获取完整列表）：

# OpenAI 行为
OPENAI_MODEL=gpt-5-mini        # gpt-5 | gpt-5-mini | gpt-5-nano | gpt-5-codex
OPENAI_REASONING_EFFORT=minimal
OPENAI_VERBOSITY=low
OPENAI_MAX_TOKENS=1_024

# 安全与性能
ENABLE_RESPONSE_CACHE=true
CACHE_MAX_SIZE_MB=100
ENABLE_RATE_LIMITING=true
MAX_REQUESTS_PER_HOUR=100

# 上下文收集
ENABLE_SERENA=false            # 当可访问Serena MCP服务器时切换为true
ENABLE_MEMORY=false            # 同上，针对MCP知识图谱
ENABLE_CCLSP=false             # 同上，针对cclsp
INCLUDE_FILE_CONTENT=true

注意 Serena，MCP 知识图谱，和 CCLSP 连接器是存根，只有在相应的MCP服务器正在运行且可访问时才会返回数据。开箱即用的收集器使用磁盘上的文件摘录作为提示中的引用。

完整参考：docs/configuration.md

Docker

本地构建和运行：

docker build -t kortx-mcp .
docker run -i --rm \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e PERPLEXITY_API_KEY=$PERPLEXITY_API_KEY \
  kortx-mcp

镜像：

使用Node.js 22 Alpine
构建期间执行 npm audit
复制编译后的 build/ 艺术品和生产依赖项
以用户 nodejs（UID 1001）运行

包含用于长时间运行的卷挂载的组合示例（docker-compose.yml）。

开发

git clone https://github.com/effatico/kortx-mcp.git
cd kortx-mcp
npm install
cp .env.example .env
npm run build
npm run dev

有用的脚本：

npm test / npm run test:coverage
npm run lint / npm run lint:fix
npm run format / npm run format:check
npm run inspector – 启动MCP Inspector进行交互式调试

需要 Node.js ≥ 22.12.0 和 npm ≥ 9。