使用说明

BuildMate发票和订单MCP服务器

一个模型上下文协议（MCP）服务器，用于通过Node.js API将Angular前端连接到DB2发票和订单数据。该服务器为发票和订单信息提供人工智能驱动的自然语言查询。

🏗️ 建筑

[Angular Chat UI] 
       ⬇️ 
 [Node.js AI Service + MCP Server]
       ⬇️
   [DB2 APIs / Knowledge Base]

🚀 特性

可用工具

搜索_语音 -按客户、状态、金额和日期范围搜索发票
get_invoice_details -获取特定发票的详细信息
get_invoices_summary -获取所有发票的汇总统计信息
搜索订单 -按客户、状态、金额和日期范围搜索订单
获取订单详情 -获取特定订单的详细信息
get_orders_summary -获取所有订单的汇总统计数据

主要特点

✅ 具有完全类型安全的TypeScript
✅ 全面的错误处理
✅ 专业BuildMate品牌
✅ 模块化服务架构
✅ 环境配置
✅ 带有拦截器的Axios HTTP客户端
✅ Zod模式验证
✅ MCP协议合规性

📋 先决条件

Node.js 18+
npm或纱线
访问BuildMate的Node.js API服务器
MCP兼容客户端（Claude Desktop，VS Code MCP扩展）

🛠️ 安装

克隆存储库
```
git clone <repository-url>
cd mcp_yt
```
安装依赖项
```
npm install
```

配置环境

# Create .env file
echo "NODEJS_API_BASE_URL=http://pub400.com:3012/api" > .env

构建项目
```
npm run build
```

🚀 用法

启动MCP服务器

# Development mode
npm run dev

# Production mode
npm start

# With inspector (for debugging)
npm run server:inspect

连接到MCP客户端

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "buildmate-mcp": {
      "command": "node",
      "args": ["path/to/your/mcp_yt/build/index.js"],
      "env": {
        "NODEJS_API_BASE_URL": "http://pub400.com:3012/api"
      }
    }
  }
}

VS代码MCP扩展

在VS代码设置中配置MCP服务器以连接到内置服务器。

🔧 配置

环境变量

变量	描述	默认值
`NODEJS_API_BASE_URL`	Node.js API服务器的基本URL	`http://pub400.com:3012/api`
`API_TIMEOUT`	API请求超时（以毫秒为单位）	`5000`
`LOG_LEVEL`	日志记录级别	`info`

API终点

服务器希望以下API终结点可用：

发票端点

GET /api/invoices -使用查询参数搜索发票
GET /api/invoices/:id -获取特定发票详细信息
GET /api/invoices/summary -获取发票汇总统计

订单端点

GET /api/orders -使用查询参数搜索订单
GET /api/orders/:id -获取具体订单详细信息
GET /api/orders/summary -获取订单汇总统计信息

健康检查

GET /api/health -API健康检查终结点

📊 示例查询

当您的MCP服务器正在运行时，您可以询问：

发票查询

“显示所有待处理的发票”
“获取发票INV-2024-001的详细信息”
“逾期发票的总金额是多少？”
“查找客户CUST-001的发票”
“显示1000美元至5000美元之间的发票”

订单查询

“显示客户ABC公司的订单”
“目前正在处理哪些订单？”
“获取订单ORD-2024-001的详细信息”
“显示所有已发货的订单”
“查找上个月下的订单”

摘要查询

“给我一份所有发票和订单的摘要”
“我们的发票总收入是多少？”
“有多少订单待交付？”

🏗️ 项目结构

src/
├── index.ts                 # Main MCP server entry point
├── config.ts               # Configuration management
└── services/
    ├── apiService.ts       # API client service
    └── toolsService.ts     # MCP tools implementation

🔍 发展

可用脚本

# Build the project
npm run build

# Run in development mode
npm run dev

# Run in production mode
npm start

# Watch mode for development
npm run watch

# Run with MCP inspector
npm run server:inspect

建筑

该项目使用TypeScript并编译为 build/ 目录：

npm run build

测试

要测试MCP服务器，请执行以下操作：

启动Node.js API服务器
运行MCP服务器： npm run dev
与MCP客户端连接
测试可用工具

🐛 故障排除

常见问题

API连接错误
- 验证 NODEJS_API_BASE_URL 是正确的
- 确保API服务器正在运行
- 检查网络连接
构建错误
- 跑 npm install 确保所有依赖项都已安装
- 检查中的TypeScript配置 tconfig.json
MCP客户端连接问题
- 验证服务器是否正在运行： npm run dev
- 检查MCP客户端配置
- 查看服务器日志中的错误

调试模式

使用MCP检查器进行调试：

npm run server:inspect

这将打开一个web界面来测试和调试您的MCP服务器。

📝 API数据模型

发票

interface Invoice {
  id: string;
  customerId: string;
  customerName: string;
  amount: number;
  status: 'paid' | 'pending' | 'overdue' | 'draft';
  dueDate: string;
  createdDate: string;
  description?: string;
}

订单

interface Order {
  id: string;
  customerId: string;
  customerName: string;
  amount: number;
  status: 'delivered' | 'shipped' | 'processing' | 'pending';
  orderDate: string;
  expectedDeliveryDate?: string;
  items: Array<{
    productId: string;
    productName: string;
    quantity: number;
    unitPrice: number;
  }>;
}

🤝 贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

📄 许可证

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

🆘 支持

有关支持和问题：

电子邮件：support@buildmate.com
电话：1-800-BUILMATE
文档：模型上下文协议

BuildMate建筑用品 -您值得信赖的优质建筑材料和用品合作伙伴。