内容
# 波浪 MCP 服务器
波浪会计的MCP服务器，通过波浪的GraphQL API提供发票、客户、产品、交易、账单、估算、税收和财务报告的访问权限。
## 功能
### 10 类别下的 54 种工具
| 类别 | 工具 | 功能 |
|---|---|---|
| **发票** | 10 | 列出、获取、创建、更新、删除、发送、批准、标记已发送、列出/记录付款 |
| **客户** | 6 | 列出、获取、创建、更新、删除、按姓名/电子邮件搜索 |
| **产品** | 5 | 列出、获取、创建、更新、存档产品和服务 |
| **账户** | 4 | 列出、获取、创建、更新会计科目表 |
| **交易** | 6 | 列出、获取、创建、更新、分类、列出附件 |
| **账单** | 6 | 列出、获取、创建、更新、列出/记录账单付款 |
| **估算** | 6 | 列出、获取、创建、更新、发送、转换为发票 |
| **税收** | 3 | 列出、获取、创建销售税 |
| **企业** | 3 | 列出、获取当前、按ID获取 |
| **报告** | 5 | 损益表、资产负债表、老龄化应收款、税务总结、现金流 |
### 17 个 MCP 应用资源
通过 `wave://apps/{name}` 可访问的预构建 UI 布局定义：
`invoice-dashboard`、`invoice-detail`、`invoice-builder`、`customer-detail`、`customer-grid`、`product-catalog`、`chart-of-accounts`、`transaction-feed`、`transaction-categorizer`、`bill-manager`、`estimate-builder`、`tax-overview`、`profit-loss`、`balance-sheet`、`cashflow-chart`、`aging-report`、`business-overview`
## 前置条件
1. 一个 [波浪](https://waveapps.com) 账户
2. 从 [波浪开发者门户](https://developer.waveapps.com/) 获取的 OAuth2 访问令牌
## 安装
```bash
npm install
npm run build
```
## 配置
```bash
# 必需
export WAVE_ACCESS_TOKEN=your_oauth2_access_token
# 可选 — 设置默认企业 ID，这样您不必每次调用都传递它
export WAVE_BUSINESS_ID=your_business_id
```
## 使用
### 直接运行
```bash
WAVE_ACCESS_TOKEN=your_token npm run dev
```
### 使用 Cursor / Claude 桌面版
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"wave": {
"command": "node",
"args": ["/path/to/wave-mcp/build/main.js"],
"env": {
"WAVE_ACCESS_TOKEN": "your_access_token",
"WAVE_BUSINESS_ID": "optional_business_id"
}
}
}
}
```
## 示例
```typescript
// 列出逾期发票
wave_list_invoices({ status: "OVERDUE" })
// 创建发票
wave_create_invoice({
customerId: "customer_456",
invoiceDate: "2026-01-15",
items: [
{ description: "Consulting", quantity: 10, unitPrice: "150.00" }
]
})
// 损益报告
wave_profit_and_loss({ startDate: "2026-01-01", endDate: "2026-03-31" })
// 搜索客户
wave_search_customers({ query: "acme" })
```
## 架构
```
src/
├── main.ts # 入口点 — 读取环境变量，启动服务器
├── server.ts # MCP 服务器设置，请求路由
├── client.ts # 波浪 GraphQL API 客户端 (gql.waveapps.com)
├── types/index.ts # 所有波浪实体的 TypeScript 类型
├── tools/
│ ├── invoices-tools.ts # 10 种发票工具
│ ├── customers-tools.ts # 6 种客户工具
│ ├── products-tools.ts # 5 种产品工具
│ ├── accounts-tools.ts # 4 种账户工具
│ ├── transactions-tools.ts # 6 种交易工具
│ ├── bills-tools.ts # 6 种账单工具
│ ├── estimates-tools.ts # 6 种估算工具
│ ├── taxes-tools.ts # 3 种税收工具
│ ├── businesses-tools.ts # 3 种企业工具
│ └── reporting-tools.ts # 5 种报告工具
└── apps/index.ts # 17 种 MCP 应用资源定义
```
所有工具都使用参数化的 GraphQL 查询针对 `https://gql.waveapps.com/graphql/public`。身份验证通过 OAuth2 Bearer 令牌进行。
## 开发
```bash
npm run build # 编译 TypeScript
npm run watch # 监视模式
npx tsc --noEmit # 类型检查不发出
```
## 许可证
MIT
