a-calc 3.0.0-beta.20260121 → 3.0.0-beta.20260124.2

package/mcp-server/README.md

@@ -0,0 +1,204 @@
+# 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

package/mcp-server/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "a-calc-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for a-calc - a powerful number precision calculation and formatting library",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "a-calc-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "a-calc",
+    "calculation",
+    "formatting",
+    "precision"
+  ],
+  "author": "Autumn",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}