Analytical MCP Server

Analytical MCP Server

为 Claude 提供 12 种分析工具的模型上下文协议服务：描述性统计、回归（线性／多项式／逻辑／多变量）、假设检验、数据预处理、数据可视化规范、多准则决策分析、机器学习模型评估、逻辑论证／谬误分析，以及由 Exa 支持的研究验证。通过 stdio 运行；分析核心无需 API 密钥（研究功能需要 EXA_API_KEY）。

设置

前置条件

• Node.js >= 20.0.0
• EXA_API_KEY 环境变量（verify_research 和 perspective_shifter 必需，这两个工具每次调用时都会请求 Exa 搜索 API）

安装

选项 1：直接安装

npm install
npm run build

选项 2：Docker

构建镜像。该服务通过 stdio 使用 MCP 协议——由 MCP 客户端启动（并将其 stdin/stdout 管道连接），而非作为分离的守护进程运行；Claude Desktop 的调用方式请参见配置中的 Docker 条目。

docker build -t analytical-mcp .

# Smoke-test the image interactively (Ctrl-C to exit):
docker run --rm -i -e EXA_API_KEY=your_api_key_here analytical-mcp

配置

直接安装配置

1. 将 .env.example 复制为 .env
2. 将你的 EXA_API_KEY 添加到 .env
3. 添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "analytical": {
      "command": "node",
      "args": ["/path/to/analytical-mcp/build/index.js"],
      "env": {
        "EXA_API_KEY": "your-exa-api-key-here"
      }
    }
  }
}

Docker 配置

1. 将 .env.example 复制为 .env
2. 将你的 EXA_API_KEY 添加到 .env
3. 添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "analytical": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", ".env",
        "-v", "$(pwd)/cache:/app/cache",
        "analytical-mcp"
      ]
    }
  }
}

可用工具

该服务启动时会无条件注册 12 个工具（注册不依赖 EXA_API_KEY；如果缺少密钥，下面两个基于研究的工具会在调用时出错）。权威列表请参见 src/tools/index.ts。

统计分析

• analyze_dataset — 对数值型或记录数组数据集进行描述性统计（汇总／统计）。
• advanced_statistical_analysis — 对表格数据（对象数组）进行描述性统计和跨变量 Pearson 相关性分析。单个数值序列请使用 analyze_dataset。
• advanced_regression_analysis — 线性、多项式、逻辑和多变量回归，由专用提供程序模块提供支持，使用真实的 OLS／逻辑回归计算（并非模拟）。
• hypothesis_testing — 真实的统计假设检验：Welch 独立样本 t 检验、配对 t 检验、相关性、卡方检验和 ANOVA，使用精确的 p 值计算（参见 src/utils/statistics.ts）。
• advanced_data_preprocessing — 对数值数据进行归一化、标准化、缺失值处理和 IQR 离群值检测。
• data_visualization_generator — 生成图表规范（散点图、折线图、条形图、直方图、箱线图、热力图、饼图、小提琴图、相关性）。

机器学习

• ml_model_evaluation — 评估模型预测：分类指标（准确率、精确率、召回率、F1）或回归指标（MSE、MAE、RMSE、R²）。

决策分析

• decision_analysis — 多准则加权决策排名。除 options 和 criteria 外，还必须提供 scores 矩阵（options.length 行 × criteria.length 列，每个值为 0-10）；weights 为可选项，默认采用等权重。这是相较于旧版文档（仅描述 options／criteria／weights）的一项不兼容要求变更。

逻辑推理

• logical_argument_analyzer — 分析论证结构、谬误、有效性和力度（通过专用提供程序类实现）。
• logical_fallacy_detector — 检测文本中的逻辑谬误并进行解释，同时提供置信度评分。
• perspective_shifter — 针对问题生成不同视角（利益相关方、学科、唱反调、乐观、悲观）。需要 EXA_API_KEY：该工具会针对每个视角领域执行一次 Exa 搜索，以便为各个视角提供依据。

研究验证

• verify_research — 从多个来源交叉验证研究结论。需要 EXA_API_KEY。返回 confidence.score（实际计算得出的 consistency/confidence 值，范围为 0-1）和 confidence.verified（布尔值：confidence.score 是否达到 minConsistencyThreshold）——该阈值是通过/失败的分界线，不会作为下限应用于报告的分数。

可观测性与指标

Analytical MCP Server 内置了 Prometheus 风格的指标 HTTP 服务（src/utils/metrics_server.ts），用于监控缓存性能和系统运行状况。

指标端点

启用后，服务会通过 HTTP 在端口 9090（可配置）提供指标：

• http://localhost:9090/metrics - Prometheus 风格的指标
• http://localhost:9090/metrics?format=json - JSON 格式的指标
• http://localhost:9090/health - 健康检查端点
• http://localhost:9090/ - 指标服务状态页

可用指标

缓存指标

• analytical_mcp_cache_hits_total - 按命名空间统计的缓存命中次数
• analytical_mcp_cache_misses_total - 按命名空间统计的缓存未命中次数
• analytical_mcp_cache_puts_total - 按命名空间统计的缓存写入次数
• analytical_mcp_cache_evictions_total - 按命名空间统计的缓存淘汰次数
• analytical_mcp_cache_size - 按命名空间统计的当前缓存大小

系统指标

• analytical_mcp_uptime_seconds - 服务运行时间（秒）
• analytical_mcp_memory_usage_bytes - 内存使用量（RSS、堆、外部）
• analytical_mcp_cpu_usage_microseconds - CPU 时间使用量（用户、系统）

配置

通过设置环境变量启用指标：

METRICS_ENABLED=true        # Enable metrics server (default: false; unauthenticated, opt-in)
METRICS_PORT=9090          # Metrics server port (default: 9090)
METRICS_HOST=127.0.0.1     # Metrics server host (default: 127.0.0.1, use 0.0.0.0 to bind to all interfaces)

使用示例

# Get Prometheus metrics
curl http://localhost:9090/metrics

# Get JSON metrics
curl http://localhost:9090/metrics?format=json

# Health check
curl http://localhost:9090/health

审计日志

每次工具调用都会向 stderr 输出一条结构化审计记录（绝不会输出到 stdout——stdout 是 MCP 协议通道），且不受 LOG_LEVEL 影响：

[2026-07-05T22:56:12.629Z] AUDIT: {"event":"tool_call","tool":"verify_research","ok":true,"durationMs":1352,"argBytes":120,"argHash":"31b769fe1f66","exaCalls":2}

每条记录都包含工具名称、结果、耗时、参数的字节大小和 SHA-256 指纹 （绝不包含原始参数值，因此不会泄露任何内容），以及 exaCalls—— 该调用发出的 Exa 出站请求数量。这为运维人员提供了取证记录（过大的输入或重复输入、意外的外部请求扩散），同时不会记录敏感内容。此功能由一个标志控制，该标志默认开启且不受 LOG_LEVEL 影响：

ENABLE_AUDIT_LOG=true   # per-call audit records to stderr (default: true)

使用示例

数据集分析

{
  "data": [23, 45, 67, 12, 89, 34, 56, 78],
  "analysisType": "stats"
}

决策分析

{
  "options": ["Option A", "Option B", "Option C"],
  "criteria": ["Cost", "Quality", "Speed"],
  "scores": [
    [7, 6, 8],
    [5, 9, 6],
    [9, 4, 7]
  ],
  "weights": [0.4, 0.4, 0.2]
}

假设检验

{
  "testType": "t_test_independent",
  "data": [[23, 45, 67, 12, 89], [34, 56, 78, 90, 21]],
  "alpha": 0.05
}

逻辑分析

{
  "argument": "All birds can fly. Penguins are birds. Therefore, penguins can fly.",
  "analysisType": "comprehensive"
}

开发

测试

# Run the offline unit suite (no API key needed) — same as test:unit
npm test

# Unit tests only (offline, no API key needed)
npm run test:unit

# Integration tests (non-blocking heads-up without EXA_API_KEY; live-Exa cases self-skip)
npm run test:integration

# Integration tests excluding the live-API suite
npm run test:integration:no-api

# Or via the thin wrapper script
./tools/test-runner.sh unit
./tools/test-runner.sh integration
./tools/test-runner.sh integration:no-api

脚本

• npm run build - 将 TypeScript 构建为 JavaScript
• npm run watch - 监视更改并重新构建
• npm run typecheck - 对 src/ 进行类型检查（不包括测试文件）
• npm run typecheck:src - 对 src/ 和集成测试进行类型检查
• npm run lint / npm run lint:fix - ESLint
• npm run format / npm run format:check - Prettier
• npm test / npm run test:unit / npm run test:integration - Jest（参见 测试）
• npm run smoke - 构建并启动真实服务，通过 stdio JSON-RPC 执行 initialize/tools-list/tools-call
• npm run cache:stats / cache:clear / cache:preload - 管理磁盘上的研究缓存
• npm run inspector - 启动 MCP inspector 进行调试

项目结构

analytical-mcp/
├── src/
│   ├── tools/           # MCP tool implementations (12 registered tools + supporting providers)
│   ├── utils/           # Utility functions, regression/NLP providers, caching, resilience, metrics
│   ├── integration/     # Integration tests (live-Exa cases self-skip without EXA_API_KEY)
│   ├── __tests__/       # Server-level protocol test (InMemoryTransport)
│   └── index.ts         # Main server entry point
├── docs/                # Documentation
├── tools/               # Development and testing scripts
├── scripts/             # Build/smoke-test scripts
└── examples/            # Usage examples

架构说明

• 提供方架构：复杂工具（回归、NLP、可视化、论证分析）被拆分为位于 src/utils/ 和 src/tools/ 中、各自职责单一的提供方模块（例如 linear_regression_provider.ts、logistic_regression_provider.ts、polynomial_regression_provider.ts、multivariate_regression_provider.ts、regression_metrics_provider.ts）。工具文件负责协调和格式化；提供方负责承载逻辑。
• 弹性：src/utils/rate_limit_manager.ts 负责处理 Exa 速率限制（密钥轮换、按端点限流）；src/utils/api_helpers.ts 提供重试功能，并使用显式的 shouldRetry 谓词。
• 缓存：src/utils/cache_manager.ts、src/utils/enhanced_cache.ts 和 src/utils/research_cache.ts 提供分层且支持命名空间的缓存（通过 ENABLE_RESEARCH_CACHE=true 启用）。
• 统计：src/utils/statistics.ts 从基本原理实现 log-gamma、不完全 beta/gamma 函数以及 t/F/卡方累积分布函数，以精确计算 p 值——不使用统计近似或模拟结果。

工具类别

统计分析

• 描述性统计：均值、中位数、标准差、四分位数
• 回归分析：线性、多项式、逻辑、多元
• 假设检验：Welch t 检验、配对 t 检验、相关性、卡方检验、ANOVA

决策支持

• 基于明确的选项 × 标准评分矩阵进行多标准加权决策排名

逻辑推理

• 论证结构、有效性和力度分析
• 谬误检测并评估置信度
• 生成不同视角

研究整合

• 通过 Exa 进行多来源验证
• 提取事实
• 检查冲突和一致性
• 评估置信度

安全与隐私

• 所有分析处理均在本地进行
• 研究功能使用 Exa API（可选，需要 EXA_API_KEY）
• 除可选的本地磁盘缓存外，不会永久存储数据
• 通过环境变量管理 API 密钥

许可证

MIT 许可证。详情请参阅 LICENSE 文件。

贡献

有关贡献工作流和规范，请参阅 CONTRIBUTING.md；完整的开发参考请参阅 docs/DEVELOPMENT.md。所有参与者都应遵守 行为准则。

简而言之：从 main 创建分支，确保 npm run typecheck、npm run lint、npm test 和 npm run smoke 全部通过，为新行为添加测试，并使用模板提交 PR。

如需报告安全漏洞，请遵循 SECURITY.md 中的说明——请勿公开提交问题。

故障排除

常见问题

JSON 解析错误：所有日志都必须输出到 stderr，而非 stdout。MCP 协议使用 stdout 进行通信。请使用 Logger 类，而非 console.log。

未显示工具：请在 Claude Desktop 设置中检查服务配置，并重启 Claude Desktop 应用程序。

研究功能在调用时失败：请在环境或 .env 文件中设置 EXA_API_KEY——verify_research 和 perspective_shifter 都需要该密钥，即使未设置时 12 个工具仍会全部注册。

服务无法启动：请检查 Node.js 版本是否为 20 或更高版本，以及是否已通过 npm install 安装所有依赖项。

详细的故障排除指南请参阅 docs/TROUBLESHOOTING.md。

调试模式

使用 MCP 检查器启动服务：

npm run inspector

链接

• Model Context Protocol 文档
• Exa API 文档
• Claude Desktop