使用说明

数学MCP服务器

一种用于数学表达式评估的安全模型上下文协议（MCP）服务器，具有严格的语法验证和全面的安全功能。

特性

安全第一设计

语法验证：在计算之前，所有表达式都会根据全面的BNF语法进行验证
功能白名单：只允许使用数学函数-不允许执行任意代码
CLI验证：验证命令行参数以确保只允许使用受支持的函数
沙盒评估：具有超时保护的安全执行环境
表达式限制：内置保护措施，防止过于复杂的表达

数学能力

算术运算：具有适当优先级的基本操作（+、-、*、/、%、^）
数学函数：三角函数、对数函数、统计函数和效用函数
常量：内置数学常数（pi、e、tau、phi等）
变量：跨表达式的变量赋值和重用
高级功能:
- 条件表达式（三元运算符）
- 逻辑运算（and，or，not）
- 比较操作（==，！=，<，<=，>，>=）
- 数组和对象表示法
- 范围表示法（a:b:c）
- 求和运算（西格玛函数）
- 单位值和成员访问权限
- 阶乘和转置运算

MCP集成

6工具 用于表达式求值和变量管理
3资源 提供语法规范和函数文档
实时验证 带有详细的错误报告
会话状态 具有持久变量上下文
可配置运行时 使用CLI选项进行细粒度控制

安装

先决条件

Node.js>=18.0.0
npm或yarn包管理器

NPM安装（推荐）

该包可以在npm上找到https://www.npmjs.com/package/math-mcp

# Install globally
npm install -g math-mcp

# Start the server
math-mcp

开发安装

# Clone the repository
git clone https://github.com/Desz01ate/math-mcp
cd math-mcp

# Install dependencies and build
npm install
npm run build

# Start the server
npm start

LLM代理的安装

Claude桌面集成

要将此MCP服务器与Claude Desktop一起使用，请首先全局安装该软件包：

npm install -g math-mcp

然后将以下配置添加到您的Claude Desktop设置中：

在 macOS 上: ~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "math-mcp": {
      "command": "math-mcp",
      "args": [],
      "env": {}
    }
  }
}

发展替代方案（来源）：

{
  "mcpServers": {
    "math-mcp": {
      "command": "node",
      "args": ["/path/to/math-mcp/dist/index.js"],
      "env": {}
    }
  }
}

其他MCP客户端

对于其他兼容MCP的客户端，您可以直接运行服务器：

# If installed globally via npm
math-mcp

# With custom configuration
math-mcp --max-expression-length 2000 --timeout 10000

# Or if running from source
npm start

# With custom configuration from source
npm start -- --max-expression-length 2000 --timeout 10000

服务器将启动并监听stdio上的MCP连接。

Docker安装

# Build the Docker image
docker build -t math-mcp .

# Run the container
docker run -it math-mcp

安装故障排除

常见问题：

“找不到命令”错误
- 确保已安装Node.js>=18.0.0： node --version
- 验证npm是否可用： npm --version
- 对于全局安装，请确保npm全局bin在PATH中
Claude Desktop未检测到服务器
- 验证中的路径 claude_desktop_config.json 是正确的
- 确保服务器成功构建： npm run build
- 检查Claude Desktop日志中的连接错误
- 配置更改后重新启动Claude Desktop
权限错误
- 使用 sudo 如果需要，用于全局npm安装
- 确保安装目录中的写入权限
- 在Windows上，如果需要，以管理员身份运行终端
构建失败
- 清除npm缓存： npm cache clean --force
- 删除node_modules并重新安装： rm -rf node_modules && npm install
- 确保安装了TypeScript依赖项
服务器启动问题
- 检查端口是否已在使用中
- 验证是否已安装所有依赖项
- 跑 npm run typecheck 检查类型错误

测试安装：

# Verify the server starts correctly
npm start

# Run the test suite
npm test

# Test with demo examples
node demo/run-all-demos.js

用法

作为MCP服务器

启动服务器：

npm start
# or
math-mcp

该服务器作为MCP服务器运行，可以与Claude Desktop或其他MCP客户端集成。

配置选项

服务器通过命令行标志支持各种配置选项：

# Basic usage
math-mcp

# With custom configuration
math-mcp --max-expression-length 2000 --timeout 10000 --allowed-functions "sqrt,sin,cos"

# Show help and available options
math-mcp --help

# Show version
math-mcp --version

可用选项：

--max-expression-length <number> -最大表达式长度（默认值：1000）
--max-recursion-depth <number> -最大递归深度（默认值：100）
--timeout <number> -评估超时（毫秒）（默认值：5000）
--allowed-functions <functions> -逗号分隔的允许函数列表
--help -显示帮助信息
--version -显示版本号

支持的功能： sqrt, cbrt, abs, sign, ceil, floor, round, sin, cos, tan, asin, acos, atan, atan2, sinh, cosh, tanh, asinh, acosh, atanh, log, log10, log2, exp, expm1, log1p, min, max, mean, median, std, var, sum, factorial, gamma

发展模式

npm run dev

运行示例

# Run all demo examples
node demo/run-all-demos.js

# Run specific demos
node demo/basic-operations.js
node demo/mathematical-functions.js
node demo/conditional-logic.js
node demo/test-summation.js
node demo/statistics-probability.js
node demo/calculus-applications.js
node demo/advanced-features.js

MCP工具

`evaluate`

对数学表达式进行全面验证。

{
  "expression": "2 * pi * radius^2",
  "validate_only": false
}

`validate_syntax`

无需求值即可验证表达式语法。

{
  "expression": "sin(x) + cos(y)"
}

`set_variable` / `get_variable`

在数学上下文中管理变量。

{
  "name": "radius",
  "expression": "5"
}

`list_variables` / `clear_variables`

列出或清除所有已定义的变量。

MCP资源

`math://grammar`

访问完整的BNF语法规范。

`math://functions`

获取所有支持的数学函数的列表。

`math://constants`

检索所有预定义的数学常数。

表达式示例

基本算术

2 + 3 * 4          // 14 (order of operations)
(2 + 3) * 4        // 20 (parentheses)
2^3 + 1            // 9 (exponentiation)
15 % 4             // 3 (modulo)

数学函数

sin(pi/2)          // 1
log(e)             // 1
sqrt(16)           // 4
abs(-5)            // 5

变量和常量

x = 5
y = 2 * x          // 10
area = pi * r^2    // Circle area

高级功能

x > 0 ? x : -x     // Absolute value using ternary
sigma(i, 1, 10, i^2)  // Sum of squares 1 to 10
[1, 2, 3, 4]       // Arrays
{x: 1, y: 2}       // Objects

条件逻辑

x > 0 and y > 0    // Logical AND
not (x == 0)       // Logical NOT
a >= b ? a : b     // Maximum using ternary

语法规范

服务器实现了全面的BNF语法，支持：

运算符：算术、逻辑、比较，具有适当的优先级
数据类型：数字、字符串、数组、对象
函数：广泛的数学函数库
控制流程：条件表达式和逻辑运算
高等数学：总结、范围、单位、成员访问权限

看 grammar.txt 通过以下方式获取完整规范或访问 math://grammar 资源。

发展

可用脚本

npm run build      # Compile TypeScript
npm run dev        # Development mode with tsx
npm start          # Start compiled server
npm test           # Run test suite
npm run test:watch # Watch mode testing
npm run lint       # ESLint checking
npm run typecheck  # Type checking only
npm run setup      # Full setup: install, build, test

配置示例

# Restrict to basic functions only
math-mcp --allowed-functions "sqrt,abs,sin,cos"

# Increase limits for complex expressions
math-mcp --max-expression-length 5000 --timeout 15000

# Minimal configuration for simple calculations
math-mcp --allowed-functions "sqrt,abs" --max-expression-length 500

项目结构

src/
├── server.ts           # MCP server implementation
├── evaluator.ts        # Secure expression evaluator
├── grammar-parser.ts   # BNF grammar parser
├── tokenizer.ts        # Lexical analyzer
├── tools/              # MCP tool implementations
├── resources/          # MCP resource handlers
└── __tests__/          # Test suite

demo/                   # Example scripts
grammar.txt            # BNF grammar specification

测试

npm test               # Run all tests
npm run test:watch     # Watch mode

测试包括：

标记器功能
语法分析器验证
表达式计算
集成场景
求和操作
CLI配置验证

安全考虑

此服务器的设计将安全性作为首要考虑因素：

无代码执行：只计算数学表达式
语法验证：所有输入都按照严格的语法进行验证
功能白名单：只有经过批准的数学函数可用
CLI验证：根据白名单验证命令行函数参数
超时保护：表达式的计算有时间限制
输入消毒：所有输入在处理前都经过适当的消毒

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题和功能请求，请使用GitHub问题跟踪器。

致谢

内置于 MCP-SDK