内容
<p align="center">
<img src="assets/icon.png" alt="Tally MCP 服务器" width="180">
</p>
# Tally MCP 服务器
一个模型上下文协议（MCP）服务器，允许 Claude 从 TallyPrime 读取和写入数据，通过其内置的 XML/HTTP 网关。
## 工作原理
```
Claude Desktop <--stdio--> ┐
├─ 此 MCP 服务器 <--HTTP/XML--> TallyPrime (localhost:9000)
远程 MCP 客户端 <--HTTP--> ┘
```
在本地，Claude Desktop 将此服务器作为 stdio 进程启动。在远程，它也可以作为 HTTP 服务器运行。无论哪种方式，工具调用都被翻译成 Tally 的 XML 请求格式，发送到 Tally 的 HTTP 网关，并返回为清理后的 JSON。还提供了一个可选的本地 SQL 缓存（PGLite），用于固定报告工具之外的临时查询。
## 先决条件
- [Node.js](https://nodejs.org) 18+
- TallyPrime 已安装、正在运行，且有公司打开
- Tally 的 HTTP 网关已启用：
`F1（帮助）> 设置 > 连接性 > 客户端/服务器配置`，并将 **TallyPrime 作为** 设置为 `两者` 或 `服务器`，端口 `9000`（默认）。
## 设置
```bash
npm install
npm run build
```
## 配置 Claude Desktop
**选项 A — 扩展（推荐）：** 打包为 `.dxt` 并一键安装。参见 [docs/EXTENSION_PACKAGING.md](docs/EXTENSION_PACKAGING.md)。
**选项 B — 手动配置：** 编辑 Claude Desktop 配置文件：
- Windows： `%APPDATA%\Claude\claude_desktop_config.json`
- macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`
添加：
```json
{
"mcpServers": {
"tally": {
"command": "node",
"args": ["D:\\Projects\\Tally-MCP-Server\\dist\\index.js"],
"env": {
"TALLY_URL": "http://localhost:9000"
}
}
}
}
```
重启 Claude Desktop。你应该会看到一个锤子/工具图标，指示 `tally` 服务器已连接。
## 可用工具
共 17 个工具 — 读取（分类账、库存、分组、凭证类型、成本中心、日记账、分类账凭证、公司信息、损益表、资产负债表、试算表、库存摘要、应收/应付账款）、写入（创建分类账、分组、库存项目、凭证）和 SQL 缓存（`sync_to_sql`、`query_sql`）。完整参考资料及参数： **[docs/TOOLS.md](docs/TOOLS.md)**。
日期使用 `DD-MM-YYYY` 格式，与 Tally 的约定相符。
## 远程运行（HTTP）
```bash
TALLY_MCP_TOKEN=<secret> npm run start:http
```
参见 [docs/HTTP_DEPLOYMENT.md](docs/HTTP_DEPLOYMENT.md)。
## 文档
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 请求流程、文件职责
- [docs/TALLY_XML_GUIDE.md](docs/TALLY_XML_GUIDE.md) — Tally 的 XML 网关工作原理、注意事项
- [docs/TOOLS.md](docs/TOOLS.md) — 完整工具参考 + 如何添加新工具
- [docs/SQL_CACHE.md](docs/SQL_CACHE.md) — PGLite SQL 缓存、架构、示例
- [docs/HTTP_DEPLOYMENT.md](docs/HTTP_DEPLOYMENT.md) — 作为远程 HTTP 服务器运行
- [docs/EXTENSION_PACKAGING.md](docs/EXTENSION_PACKAGING.md) — 打包为 `.dxt` Claude Desktop 扩展
## 项目结构
```
src/
tally.ts Tally HTTP 客户端：发送 XML，处理连接/超时错误
clean.ts 规范化 Tally 的原始 XML->JSON 为可预测的 JSON
templates.ts 渲染 templates/ 中的 Nunjucks XML 模板
db.ts PGLite SQL 缓存：sync_to_sql / query_sql
tools.ts MCP 工具定义 + XML 请求生成器
server.ts 共享 MCP 服务器构造（用于两个入口点）
index.ts stdio 入口点（本地 Claude Desktop）
http-server.ts HTTP 入口点（远程客户端）
templates/
*.xml.njk 每个 Tally XML 请求形状的 Nunjucks 模板
manifest.json Claude Desktop 扩展（.dxt）清单
```
## 环境变量
| 变量 | 默认值 | 目的 |
|---|---|---|
| `TALLY_URL` | `http://localhost:9000` | Tally 的 HTTP 网关地址 |
| `PORT` | `3939` | `npm run start:http` 的端口 |
| `TALLY_MCP_TOKEN` | _(未设置)_ | 如果设置，HTTP 服务器 `/mcp` 端点的 Bearer Token |
## 故障排除
- **"无法访问 TallyPrime"** — Tally 未运行，或 HTTP 网关未在端口 9000 上启用。
- **"Tally 返回空响应"** — Tally 正在运行，但未打开任何公司。
- **`create_ledger` / `create_voucher` 失败并报错** — 检查父分组/分类账名称是否与 Tally 中存在的名称完全匹配（名称区分大小写，必须完全匹配）。
## 路线图 / 尚未支持
- 编辑或删除现有凭证/分类账/主记录
- 库存凭证（库存日记账、制造日记账等）
- 特定于 GST 的报告（GSTR-1、GSTR-3B）
- 多公司支持（当前始终针对打开的公司）
