Waly MCP Server

瓦利CRM MCP服务器

用于AI代理与Waly CRM集成的模型上下文协议（MCP）服务器。该服务器提供6个类别的27个工具，使AI代理能够与您的CRM系统交互，以管理管道、交易、联系人、产品和生成分析。

🚀 特性

• 多租户支持：为多个组织提供服务的单个实例
• 综合工具：涵盖所有核心CRM运营的27个工具
• 读写操作：对管道、交易、阶段、联系人和产品的全面CRUD支持
• 分析与洞察：生成报告、统计数据和看板快照
• 安全认证：使用现有Chatwoot令牌系统进行承载令牌身份验证
• 类型安全：使用TypeScript构建，以提高可靠性和开发人员体验

📦 可用工具

管道（5个工具）

• list_pipelines -列出所有销售渠道
• get_pipeline_details -通过阶段和交易获取管道详细信息
• create_pipeline -创建新管道
• update_pipeline -更新管道属性
• delete_pipeline -删除管道（级联到阶段和交易）

优惠（7工具）

• list_deals -列表处理高级过滤
• get_deal_details -获取完整的交易信息
• create_deal -创建新交易
• update_deal -更新交易属性
• move_deal_to_stage -将交易转移到不同阶段
• delete_deal -删除交易
• get_deal_activities -获取交易活动时间表

阶段（4个工具）

• list_stages -列出管道阶段（看板列）
• create_stage -创建新舞台
• update_stage -更新阶段属性
• delete_stage -删除阶段（需要空阶段）

联系人（5个工具）

• list_contacts -列出所有联系人/客户
• get_contact_details -获取相关交易的联系方式
• create_contact -创建新联系人
• update_contact -更新联系信息
• search_contacts -按姓名/电子邮件/电话搜索联系人

产品（4个工具）

• list_products -列出产品目录
• get_product_details -获取产品详细信息（包括AI分析）
• list_product_categories -列出产品类别
• add_product_to_deal -将产品链接到交易

分析（2个工具）

• get_pipeline_analytics -综合管道统计
• get_kanban_snapshot -完整的看板视图

🛠️ 安装

1.安装依赖项

cd mcp-server
npm install

2.构建服务器

npm run build

这将TypeScript编译为JavaScript dist/ 文件夹。

⚙️ 配置

服务器是通过环境变量配置的：

环境变量

创建一个 .env 文件在 mcp-server/ 目录：

# Required: Base URL of your Waly CRM API
CRM_API_URL=http://localhost:3000/api

# Optional: Default bearer token for authentication
# If not set, token must be provided with each request
CRM_BEARER_TOKEN=your_chatwoot_bearer_token_here

获得不记名代币

1. 登录您的Waly CRM
2. 转到组织设置
3. 导航到API/集成部分
4. 生成或复制您的Chatwoot集成令牌
5. 将此令牌用作 CRM_BEARER_TOKEN

或者，可以根据请求提供令牌，包括 _bearerToken 在工具论证中。

🚀 运行服务器

发展模式

npm run dev

在监视模式下运行TypeScript编译器。根据文件更改进行重建。

生产模式

npm start

从运行编译后的服务器 dist/index.js.

🔌 与AI代理集成

Claude桌面集成

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "waly-crm": {
      "command": "node",
      "args": [
        "/absolute/path/to/waly-crm/mcp-server/dist/index.js"
      ],
      "env": {
        "CRM_API_URL": "http://localhost:3000/api",
        "CRM_BEARER_TOKEN": "your_token_here"
      }
    }
  }
}

其他MCP客户端

服务器使用stdio传输并遵循标准MCP协议。它可以与任何兼容MCP的客户端集成：

# Direct execution
node mcp-server/dist/index.js

# With environment variables
CRM_API_URL=http://localhost:3000/api CRM_BEARER_TOKEN=token node mcp-server/dist/index.js

📖 使用示例

示例1：列出所有管道

// AI agent calls:
list_pipelines()

// Returns:
{
  "pipelines": [
    {
      "id": "clx1...",
      "name": "Sales Pipeline",
      "stages": [...],
      "_count": { "deals": 15 }
    }
  ],
  "count": 1
}

示例2：获取管道分析

// AI agent calls:
get_pipeline_analytics({
  "pipelineId": "clx1..."
})

// Returns:
{
  "pipelineId": "clx1...",
  "pipelineName": "Sales Pipeline",
  "totalDeals": 15,
  "totalValue": 45000,
  "dealsByStage": [
    {
      "stageName": "Lead",
      "dealCount": 5,
      "totalValue": 10000
    },
    ...
  ],
  "conversionRate": "33.33",
  "averageDealValue": "3000.00"
}

示例3：创建交易

// AI agent calls:
create_deal({
  "title": "New Enterprise Client",
  "value": 50000,
  "currency": "USD",
  "priority": "high",
  "pipelineId": "clx1...",
  "stageId": "clx2...",
  "contactId": "clx3..."
})

// Returns:
{
  "success": true,
  "deal": { ... },
  "message": "Deal 'New Enterprise Client' created successfully"
}

示例4：在阶段之间移动交易

// AI agent calls:
move_deal_to_stage({
  "dealId": "clx4...",
  "stageId": "clx5..."
})

// Automatically creates activity record and returns updated deal

示例5：获取看板快照

// AI agent calls:
get_kanban_snapshot({
  "pipelineId": "clx1..."
})

// Returns complete kanban view:
{
  "pipelineId": "clx1...",
  "pipelineName": "Sales Pipeline",
  "stages": [
    {
      "id": "clx2...",
      "name": "Lead",
      "dealCount": 5,
      "deals": [
        {
          "id": "clx4...",
          "title": "Deal 1",
          "value": 5000,
          "priority": "high",
          "contact": { ... },
          "assignedTo": { ... }
        }
      ]
    }
  ]
}

🔐 身份验证和安全

多租户隔离

服务器通过承载令牌强制执行组织级隔离：

1. 每个请求都包含一个承载令牌
2. 令牌根据CRM的身份验证系统进行验证
3. CRM会自动按令牌的组织过滤所有数据
4. 行级安全确保数据隔离

令牌来源

代币可以通过两种方式提供：

1. 环境变量 （建议用于单一组织部署）：

   CRM_BEARER_TOKEN=your_token_here

1. 根据请求 （建议用于多组织场景）：

   create_deal({
     "_bearerToken": "org_specific_token",
     "title": "New Deal",
     ...
   })

订阅限制

服务器遵守CRM订阅限制：

• 创建管道检查管道限制（如果超过，则返回402）
• 创建交易检查交易限额（如果超过，则返回402）
• 其他操作遵循组织权限

🏗️ 建筑

mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── config.ts             # Configuration management
│   ├── auth.ts               # Authentication utilities
│   ├── tools/
│   │   ├── pipelines.ts      # Pipeline tools
│   │   ├── deals.ts          # Deal tools
│   │   ├── stages.ts         # Stage tools
│   │   ├── contacts.ts       # Contact tools
│   │   ├── products.ts       # Product tools
│   │   └── analytics.ts      # Analytics tools
│   └── utils/
│       ├── api-client.ts     # HTTP client wrapper
│       └── validators.ts     # Zod validation schemas
├── package.json
├── tsconfig.json
└── README.md

设计原则

1. API-第一个：所有操作都调用现有的REST API（没有直接的数据库访问）
2. 无状态：每个请求都是独立的
3. 类型安全：对所有输入进行Zod验证
4. 错误处理：全面的错误消息和状态代码
5. 符合标准：严格遵循MCP规范

🧪 测试

手动测试

您可以使用MCP Inspector测试服务器：

npx @modelcontextprotocol/inspector node dist/index.js

这将打开一个web UI，您可以在其中：

• 查看所有可用工具
• 使用自定义参数调用工具
• 实时查看响应

测试单个工具

# Set environment
export CRM_API_URL=http://localhost:3000/api
export CRM_BEARER_TOKEN=your_token

# Run server
node dist/index.js

# In another terminal, use MCP client or inspector

🐛 故障排除

服务器无法启动

# Check that TypeScript compiled successfully
npm run build

# Check for compilation errors
ls -la dist/

# Verify environment variables
echo $CRM_API_URL
echo $CRM_BEARER_TOKEN

身份验证错误

Error: No bearer token provided

解决方案：设置 CRM_BEARER_TOKEN 环境变量或包括 _bearerToken 根据要求。

连接被拒绝

Failed to connect to API

解决方案：验证 CRM_API_URL 指向正在运行CRM实例。检查端口是否正确。

402需要付款

Pipeline limit reached

解决方案：这是超出订阅限制时的预期行为。升级订阅或删除未使用的资源。

🔄 发展

添加新工具

1. 在适当的文件中创建工具定义（例如。， tools/deals.ts):

export const myNewTool = {
  name: 'my_new_tool',
  description: 'Does something cool',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    },
    required: ['param']
  }
};

1. 实现处理函数：

export async function handleMyNewTool(client: CRMApiClient, args: unknown) {
  const { param } = validateArgs(schema, args);
  const response = await client.get('/endpoint');
  return response.data;
}

1. 添加到工具列表和处理程序开关语句

1. 重建和测试

API变更

如果CRM API发生变化：

1. 更新 utils/api-client.ts 如有需要
2. 更新中的工具实现 tools/*.ts
3. 更新验证器 utils/validators.ts
4. 彻底重建和测试

📊 性能注意事项

• 缓存：考虑为频繁访问的数据添加响应缓存
• 速率限制：如果为多个并发代理提供服务，则实施速率限制
• 批量操作：对于批量操作，考虑添加批处理工具
• 分页：大列表可能受益于分页支持

🤝 贡献

贡献时：

1. 使用TypeScript维护类型安全
2. 为所有新输入添加Zod验证
3. 遵循现有代码结构
4. 更新文档
5. 使用真实CRM实例进行测试

📝 许可证

麻省理工学院

🆘 支持

对于问题和疑问：

1. 请先查看此自述文件
2. 审查 MCP文件
3. 查看Waly CRM API文档
4. 在存储库中打开问题

______________________________________________________________________

内置于❤️ 瓦利CRM