Qontak MCP

Qontak MCP

⚠️ 实验项目 ⚠️ 该项目目前正在进行中 积极开发 并且应该被认为是实验性的。 虽然经过了彻底的测试，但在生产使用之前还需要进一步的实际验证。 API和功能可能会更改，恕不另行通知。使用风险自负。 欢迎社区反馈和贡献！

Qontak MCP是一个模型上下文协议（MCP）服务器，它提供 61智能工具 用于管理Qontak CRM中的联系人、公司、交易、工单、任务、笔记、产品和产品关联 动态场发现.

特性

核心能力

• 61智能MCP工具 用于全面的Qontak CRM运营

- 联系人（10个工具）：通过模板发现、CRUD、时间线、聊天历史记录完成联系人管理 - 公司（8种工具）：全面的公司管理，动态的现场支持 - 优惠（14工具）：完整的交易生命周期管理，包括管道/阶段感知必填字段、聊天历史、权限 - 门票（7工具）：具有管道特定现场要求的完整票务工作流程 - 任务（8个工具）：具有自动状态、详细信息和next_step字段发现功能的任务管理 - 注释（5个工具）：与实体协会（联系人、公司、交易）一起创建和管理笔记 - 产品（5个工具）：支持定价和SKU的产品目录管理 - 产品协会（5个工具）：将产品链接到交易、联系人或公司

• 动态现场发现 -游戏规则改变者：

- 🚀 零硬编码值 -在运行时从API模板中发现的所有必需字段 - 🎯 智能分类 -自动识别必填字段和可选字段 - 🔄 API驱动的验证 -当Qontak CRM现场要求发生变化时自动适应 - 📊 特定资源逻辑 -交易、票证和任务的不同发现策略

• 生产就绪架构:

- ✅ 多租户支持：可插入的令牌存储，具有按用户隔离功能 - ✅ 自动令牌管理：延迟刷新，6小时缓存（Redis/Vault） - ✅ 三个存储后端：环境（开发）、Redis（暂存）、Vault（生产） - ✅ 速率限制：具有每个用户和全局限制的令牌桶算法 - ✅ 安全第一：Pydantic验证、结构化日志记录、敏感数据编辑

• 久经考验的质量:

- ✅ 808项测试，涵盖所有功能 - ✅ 15个带有真实API验证的集成测试文件 - ✅ 100%动态字段发现已验证 - ✅ 核心模块的代码覆盖率达到96% - ✅ 100%覆盖身份验证和所有8个工具模块 - ✅ API客户端91%的覆盖率，提供全面的错误处理

令牌存储选择

根据您的环境选择合适的令牌存储：

⚠️ 重要: env 和 redis 商店是为了 仅用于开发和分期. 对于生产部署，请使用 vault 其在静止时提供加密， 审计日志记录和细粒度访问控制。

为什么使用Redis或Vault而不是Env？

环境商店(env):

• ❌ 无访问令牌缓存
• ❌ 刷新每个API请求的令牌
• ❌ 性能变慢
• ❌ Qontak OAuth端点负载更高
• ✅ 简单的设置，可快速进行本地测试

Redis商店(redis):

• ✅ 缓存访问令牌6小时
• ✅ 仅在令牌过期时刷新
• ✅ 更快的API调用
• ✅ 减少Qontak OAuth端点的负载
• ✅ 多租户支持
• ⚠️ 仅供开发/分期使用

保险库商店(vault):

• ✅ 所有Redis的好处加上：
• ✅ 静态加密
• ✅ 审核日志记录
• ✅ 细粒度访问控制
• ✅ 生产就绪安全

安装

先决条件

• Python 3.10+
• 具有API访问权限的Qontak CRM帐户

设置

# Clone the repository
git clone https://github.com/deptz/qontak-mcp.git
cd qontak-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
.\venv\Scripts\activate   # Windows

# Install dependencies based on your environment:
pip install -e .              # Local dev (env store only)
pip install -e ".[redis]"     # Dev/Staging (with Redis)
pip install -e ".[vault]"     # Production (with Vault)
pip install -e ".[all]"       # All backends

# Configure credentials
cp .env.example .env
# Edit .env and add your configuration

这 .env.example 文件包含以下各项的所有配置选项：

• MCP服务器（生产用途）
• 集成测试（开发用途）
• 所有令牌存储后端（env、redis、vault）

配置

所有配置都是通过环境变量完成的 .env 文件或导出到shell中。

快速设置

地方发展（简单）：

cp .env.example .env
# Edit .env and set:
# QONTAK_REFRESH_TOKEN=your_token_here
# TOKEN_STORE=env  (default)

使用Redis进行开发（推荐）：

cp .env.example .env
# Edit .env and set:
# QONTAK_REFRESH_TOKEN=your_token_here
# TOKEN_STORE=redis
# REDIS_URL=redis://localhost:6379/0  (default)

环境变量引用

必需的

令牌存储选择

Redis配置（当TOKEN_STORE=Redis时）

保险库商店（生产）✅ 推荐

保险库设置（生产）

1. 启用KV v2机密引擎：

vault secrets enable -path=secret kv-v2

1. 为MCP服务器创建策略：

# qontak-mcp-policy.hcl
path "secret/data/qontak/tokens/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
path "secret/metadata/qontak/tokens/*" {
  capabilities = ["read", "delete", "list"]
}

1. 应用策略：

vault policy write qontak-mcp qontak-mcp-policy.hcl

1. 使用策略生成令牌：

vault token create -policy=qontak-mcp

获取刷新令牌

1. 登录您的Qontak CRM帐户
2. 转到API令牌设置： https://crm.qontak.com/crm/api_token/
3. 如果不存在，则创建新令牌
4. 复制生成的刷新令牌

Redis快速入门（推荐用于开发）

Redis通过缓存访问令牌提供了显著的性能改进：

# 1. Install with Redis support
pip install -e ".[redis]"

# 2. Start Redis (choose one method)
# Docker (easiest):
docker run -d -p 6379:6379 --name redis-qontak redis:alpine

# Homebrew (macOS):
brew install redis && brew services start redis

# Or direct:
redis-server --daemonize yes

# 3. Verify Redis is running
redis-cli ping  # Should return: PONG

# 4. Configure environment
export TOKEN_STORE=redis
export QONTAK_REFRESH_TOKEN="your_refresh_token_here"

# 5. Run the server
qontak-mcp

性能比较：

• 没有Redis (env 存储）：每次API调用约500ms（包括OAuth刷新）
• 使用Redis (redis 存储）：每次API调用约50-100ms（缓存令牌，速度快10倍！）

访问令牌将缓存6小时，并在过期时自动刷新。

用法

运行服务器

# Run the MCP server
qontak-mcp

可用工具

联系人（10个工具）

公司（8种工具）

优惠（14工具）

门票（7工具）

任务（8个工具）

注释（5个工具）

产品（5个工具）

产品协会（5个工具）

自定义字段

所有资源（交易、门票、任务）都支持使用通用数组格式的动态自定义字段：

{
  "additional_fields": [
    {
      "id": 14840254,
      "name": "field_name",
      "value": "field_value",
      "value_name": null
    }
  ]
}

处理自定义字段的工作流：

1. 查找必填字段 使用适当的工具：

- get_required_fields_for_deal(pipeline_id, stage_id) -对于交易 - get_required_fields_for_ticket(pipeline_id) -对于门票 - get_required_fields_for_task() -对于任务

1. 获取字段详细信息 包括：

- 字段名称和ID - 字段类型（单行文本、下拉选择、数字等） - 下拉选项（如适用） - 管道/阶段是否需要现场

1. 构建additional_fields数组 带有必需的自定义字段

1. 创建/更新资源 有完整的数据

支持的字段类型：

• ✅ 单行文本、文本区域、数字、日期、日期时间
• ✅ 下拉选择、多选、百分比、清单、URL
• ⚠️ 照片、签名、文件上传、GPS（需要单独的上传机制）

看 FIELD_LIMITATIONS.md 获取详细的字段类型文档。

多租户使用

所有工具都接受可选 user_id 多租户场景的参数：

# Single tenant (default)
list_deals(page=1, per_page=25)

# Multi-tenant
list_deals(page=1, per_page=25, user_id="tenant-123")

建筑

┌─────────────────────────────────────────┐
│             MCP Tools (61)              │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│            QontakClient                 │
│       (async HTTP + auto auth)          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│            QontakAuth                   │
│         (lazy token refresh)            │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                   TokenStore (Protocol)                     │
├─────────────────┬─────────────────┬─────────────────────────┤
│   EnvTokenStore │ RedisTokenStore │    VaultTokenStore      │
│   (Local Dev)   │  (Dev/Staging)  │     (Production)        │
│       ⚠️        │       ⚠️        │         ✅              │
└─────────────────┴─────────────────┴─────────────────────────┘

Kimi代码CLI技能

此存储库包括 Qontak MCP开发人员技能 为了 Kimi代码命令行界面 它在处理代码库时提供智能帮助。

包含什么

该技能为两者提供了全面的文档 用户 和 开发者:

对于用户：

• 使用指南：如何通过示例和工作流程使用所有61个MCP工具
• 自定义字段指南：使用动态字段和additional_field
• 常见工作流：销售渠道、支持票、数据导入模式

对于开发者：

• 4个核心工作流程：添加新工具、创建令牌存储、实现动态字段发现、调试测试
• 架构指南：系统组件、数据流、安全层
• 工具样式：所有6个工具类别的完整模式（列表、获取、创建、更新、模板、动态字段）
• 域引用：特定资源指南（交易、联系人、公司、门票、任务、笔记、产品）
• 测试模式：夹具、单元/集成测试模式、覆盖配置
• 锅炉板发生器：构建新工具的脚本

技能位置

.agents/skills/qontak-mcp-developer/
├── SKILL.md                    # Entry point with workflows
├── scripts/
│   └── add_tool.py             # Tool boilerplate generator
└── references/
    ├── usage_guide.md          # How to use the MCP (for end users)
    ├── architecture.md         # System architecture
    ├── tool_patterns.md        # Tool implementation patterns
    ├── dynamic_fields.md       # Field discovery patterns
    ├── token_stores.md         # Token store backend guide
    ├── testing.md              # Testing patterns
    ├── models.md               # Pydantic model patterns
    └── domains/                # Resource-specific guides
        ├── deals.md
        └── contacts.md

使用技能

在此存储库中使用Kimi Code CLI时，该技能会自动激活以下请求：

对于用户：

• “如何使用自定义字段创建交易？”
• “添加联系人的工作流程是什么？”
• “我如何将交易推进到下一阶段？”
• “门票的必填字段是什么？”
• “我如何将产品与交易联系起来？”

对于开发者：

• “为交易标签添加新工具”
• “如何创建新的令牌存储后端？”
• “实现票证的动态字段发现”
• “修复联系人验证测试”
• “解释交易管道要求”

手动技能使用

为新工具生成样板：

cd .agents/skills/qontak-mcp-developer
python scripts/add_tool.py deals get_deal_tags get_deal_tags

发展

请阅读 贡献.md 有关我们的行为准则以及向我们提交pull请求的流程的详细信息。

# Install dev dependencies
pip install -e ".[all,dev]"

# Run tests
pytest

# Type checking
mypy src/

社区

• 行为准则
• 安全策略
• 更新日志

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。