# a-calc MCP Server

为 [a-calc](https://github.com/Autumn-one/a-calc-old) 库提供的 MCP (Model Context Protocol) 服务器，让 AI 助手能够使用 a-calc 进行精确的数字计算和格式化。

## 功能特性

### Tools (工具)

| 工具名 | 描述 |
|--------|------|
| `calc` | 核心计算函数 - 支持表达式计算、变量填充、格式化 |
| `fmt` | 专用格式化函数 - 跳过表达式解析，性能更优 |
| `calc_sum` | 聚合计算函数 - 对数组数据批量计算并求和 |
| `basic_calc` | 基础运算函数 - 直接进行精确的数学运算 |
| `get_acalc_guide` | 获取使用指南和最佳实践 |

### Resources (资源)

| 资源 URI | 描述 |
|----------|------|
| `acalc://api/overview` | API 完整参考文档 |
| `acalc://guide/formatting` | 格式化规则详解 |
| `acalc://guide/best-practices` | 最佳实践指南 |
| `acalc://examples/common` | 常见使用示例 |

### Prompts (提示模板)

| 提示名 | 描述 |
|--------|------|
| `financial_calculation` | 金融计算场景 - 价格、税费、折扣等 |
| `data_formatting` | 数据格式化场景 - 千分位、百分比等 |
| `batch_calculation` | 批量计算场景 - 数组聚合、报表统计 |
| `code_review` | 代码审查 - 检查数字计算是否可优化 |

## 安装

a-calc MCP 服务器已集成到 a-calc 主包中。

**推荐：项目本地安装**

```bash
npm install a-calc
```

## 使用方法

### 配置 Claude Desktop

在 Claude Desktop 配置文件中添加：

**配置文件位置：**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`

**配置：**

```json
{
  "mcpServers": {
    "a-calc": {
      "command": "npx",
      "args": ["a-calc-mcp"]
    }
  }
}
```

> 💡 **说明：**
> - Claude Desktop 默认工作目录为项目根目录，会自动使用项目本地安装的 a-calc（如果有）
> - 如果项目未安装 a-calc，npx 会自动下载最新版本

### 故障排除

如果 MCP 服务器无法正常运行，请按以下顺序尝试：

**1. 添加 `cwd` 配置项**

某些 MCP 客户端（如 Trae）可能需要显式指定工作目录：

```json
{
  "mcpServers": {
    "a-calc": {
      "command": "npx",
      "args": ["a-calc-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

**2. 全局安装**

如果还是不生效，可以尝试全局安装：

```bash
npm install -g a-calc
```

然后使用：

```json
{
  "mcpServers": {
    "a-calc": {
      "command": "a-calc-mcp"
    }
  }
}
```

**3. Windows 平台特殊说明**

如果在 Windows 上遇到 `Windows requires 'cmd /c' wrapper to execute npx` 错误，将 `npx` 改为 `cmd /c npx`：

```json
{
  "mcpServers": {
    "a-calc": {
      "command": "cmd",
      "args": ["/c", "npx", "a-calc-mcp"]
    }
  }
}
```

### 配置其他 MCP 客户端

对于其他支持 MCP 的客户端，使用 stdio 传输方式连接：

```bash
# 使用 npx（推荐）
npx a-calc-mcp

# 全局安装后
a-calc-mcp
```

## 使用示例

### 在 AI 对话中使用

```
用户：帮我计算 0.1 + 0.2 的精确结果

AI：[调用 calc 工具]
结果：0.3
```

```
用户：把 1234567.89 格式化为千分位显示，保留2位小数

AI：[调用 fmt 工具]
结果：1,234,567.89
```

```
用户：计算这些订单的总金额：
- 商品A：单价 99.9，数量 2
- 商品B：单价 49.9，数量 3

AI：[调用 calc_sum 工具]
结果：349.50
```

### 获取使用指南

```
用户：如何使用 a-calc 进行金额计算？

AI：[调用 get_acalc_guide 工具，topic: "best_practices"]
[返回最佳实践文档]
```

## 开发

### 目录结构

```
mcp-server/
├── src/
│   └── index.js      # 主入口文件
├── package.json
└── README.md
```

### 添加新工具

在 `src/index.js` 中的 `TOOLS` 数组添加新工具定义，并在 `execute_tool` 函数中实现对应逻辑。

### 添加新资源

在 `RESOURCES` 数组添加资源定义，在 `RESOURCE_CONTENTS` 对象添加资源内容。

## 相关链接

- [a-calc GitHub](https://github.com/Autumn-one/a-calc-old)
- [a-calc npm](https://www.npmjs.com/package/a-calc)
- [MCP 协议文档](https://modelcontextprotocol.io/)

## License

MIT