CATS MCP Server

CATS MCP服务器

用于CATS（完整申请人跟踪系统）API v3的FastMCP服务器，带有动态工具集加载。

概述

此MCP服务器提供对以下内容的访问 228工具 横跨 17套工具 涵盖完整的CATS API v3。工具集架构允许代理只加载他们需要的东西，从而优化令牌的使用和性能。

主要特点：

• 🎯 228个MCP工具 覆盖所有CATS API v3端点（完全覆盖）
• 📦 17套工具 按资源类型组织
• ⚡ 动态负载 -只装载你需要的东西
• 🔐 安全 -基于令牌的身份验证，无硬编码凭据
• 📝 类型安全 -所有工具的完整类型提示
• 📚 有据可查 -带示例的综合文档字符串
• 🚀 生产准备就绪 -错误处理，异步/等待，已测试
• ☁️ FastMCP云就绪 -从GitHub自动部署
• 📊 监控 -健康检查和结构化日志记录

快速开始

选项1:FastMCP云（推荐）

通过自动GitHub部署部署到托管云：

# 1. Ensure fastmcp.json exists (already created)
# 2. Push to GitHub
# 3. Create project at https://fastmcp.app
# 4. Set CATS_API_KEY environment variable
# 5. Deploy automatically - done!

# Access at: https://your-project-name.fastmcp.app/mcp

看 FASTCMP_CLOUD_DEPLOYMENT.md 完整的指南。

方案2：地方发展

# 1. Install dependencies
pip install fastmcp httpx python-dotenv

# 2. Configure
cp .env.example .env
# Edit .env with your CATS_API_KEY

# 3. Run
python server.py --list-toolsets  # See available toolsets
python server.py                  # Load default toolsets (89 tools)
python server.py --toolsets all   # Load all 162 tools

建筑

工具集组织

默认工具集（105个工具） -默认加载：

• 候选人 （44个工具）-完整的候选人管理+所有子资源
• 工作 （35个工具）-完整的作业管理、列表、应用程序、状态
• 管道 （17个工具）-工作流和状态管理
• 上下文 （3个工具）-站点信息、用户信息、授权
• 任务 （5个工具）-任务管理

招聘工具集（106个工具） -可选：

• 公司 （48个工具）-完成公司管理+电话、部门、列表、状态、缩略图
• 联系人 （42个工具）-完整的联系人管理+列表、状态、缩略图
• 活动 （6个工具）-活动跟踪（电话、会议、电子邮件）
• 门户 （8个工具）-职业门户和应用程序
• 工作历史 （3个工具）-就业历史管理

数据和配置工具集（22个工具） -可选：

• 标签 （2个工具）-全局标签管理
• 网络钩子 （4个工具）-具有24种以上事件类型的Webhook订阅
• 用户 （2个工具）-用户和权限管理
• 触发器 （2个工具）-自动触发信息
• 附件 （4个工具）-文件管理+AI简历解析
• 备份 （3个工具）-数据库备份管理
• 事件 （5个工具）-日历事件和日程安排

代币效率

代理只加载所需的工具集，大大减少了令牌的使用：

安装

1.设置

# Clone repository
cd cats-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install fastmcp httpx python-dotenv

2.配置

创建 .env 文件：

CATS_API_BASE_URL=https://api.catsone.com/v3
CATS_API_KEY=your_cats_api_key_here

# Optional: Default toolsets
CATS_TOOLSETS=candidates,jobs,companies

3.添加到克劳德桌面

编辑 ~/.claude/config.json:

{
  "mcpServers": {
    "cats": {
      "command": "python",
      "args": ["/path/to/cats-mcp-server/server.py"],
      "env": {
        "CATS_API_BASE_URL": "https://api.catsone.com/v3",
        "CATS_API_KEY": "your_api_key",
        "CATS_TOOLSETS": "candidates,jobs,companies"
      }
    }
  }
}

用法

命令行

# List toolsets
python server.py --list-toolsets

# Default (77 tools)
python server.py

# Specific toolsets
python server.py --toolsets candidates,jobs,companies

# Everything (163 tools)
python server.py --toolsets all

# Environment variable
export CATS_TOOLSETS='candidates,pipelines'
python server.py

常见组合

# Recruiting team
--toolsets candidates,jobs,pipelines,companies,activities

# Hiring manager
--toolsets candidates,jobs,pipelines,events

# Administrator
--toolsets users,webhooks,backups,triggers,tags

# Full access
--toolsets all

API覆盖范围

完整工具清单

候选人（44种工具） -全面覆盖

• Main：列表、获取、创建、更新、删除、搜索、过滤、授权
• 子资源：管道、活动、附件、自定义字段（含详细信息）、电子邮件（完整CRUD）、电话（完整CRUD

工作（35工具） -全面覆盖

• Main：列表、获取、创建、更新、删除、搜索、过滤
• 子资源：活动、附件、自定义字段（带详细信息）、标签、状态（完全管理）
• 作业列表：完整的CRUD+项目管理
• 应用程序：列表、获取详细信息、获取字段

管道（17个工具） -全面覆盖

• Main：列表、获取、创建、更新、删除、过滤
• 工作流：列出工作流、获取工作流、列出工作流状态、获取工作流状态
• 状态管理：获取历史记录，更改状态

公司（48种工具） -全面覆盖

• Main：列表、获取、创建、更新、删除、搜索、过滤
• 子资源：活动、附件、联系人、自定义字段（带详细信息）、管道、标签
• 高级：电话（完整的CRUD）、部门（完整的CRUD）、列表（完整的Crude）、状态、缩略图

联系人（42个工具） -全面覆盖

• Main：列表、获取、创建、更新、删除、搜索、过滤
• 子资源：活动、附件、自定义字段（带详细信息）、电子邮件（完整CRUD）、电话（完整CRUD”）、管道、标签
• 高级：列表（完整CRUD）、状态、缩略图

活动（6个工具）

• 列表、获取、更新、删除、搜索、过滤
• 类型：电子邮件、会议、call_talked、call_lvm、call_missed、text_message、其他

门户网站（8个工具）

• 列出、获取、列出作业
• 提交申请、发布/取消发布作业
• 登记表

工作历史（3个工具）

• 获取、更新、删除

标签（2个工具）

• 列表，获取

Webhooks（4个工具）

• 列表、获取、创建、删除
• 24+事件类型，具有HMAC-SHA256验证

用户（2个工具）

• 列表，获取
• 访问级别：只读、编辑、管理员

触发器（2个工具）

• 列表，获取

附件（4个工具）

• 获取、删除、下载
• parse_resume -基于人工智能的简历解析

备份（3个工具）

• 列表、获取、创建
• 选项：附件、电子邮件

活动（5个工具）

• 完整CRUD：列表、获取、创建、更新、删除
• 与会者、虚拟会议URL、日历集成

上下文（3个工具）

• get_site、get_me、authorized_user

任务（5个工具）

• 完整的CRUD，包括优先级、任务、截止日期

发展

文件结构

cats-mcp-server/
├── server.py                  # Core (242 lines)
├── toolsets_default.py        # Default (1,611 lines, 77 tools)
├── toolsets_recruiting.py     # Recruiting (1,364 lines, 64 tools)
├── toolsets_data.py           # Data (1,017 lines, 22 tools)
├── .env                       # Config (not in git)
├── .env.example               # Template
├── README.md                  # This file
└── cats-v3-api-endpoints.md   # API reference

测试

# Syntax check
python -m py_compile server.py toolsets_*.py

# List toolsets
python server.py --list-toolsets

# Test loading
python server.py --toolsets candidates

故障排除

常见问题

“未配置CATS_API_KEY”

• 产生 .env 或作为环境变量导出

**“找不到模块：工具集\_\*”**

• 确保所有三个工具集文件都存在

速率限制（500需求/小时）

• 监视器 X-Rate-Limit-Remaining 头球
• 对429个错误实施回退

401未经授权

• 验证API v3密钥（不是v2）
• 检查密钥权限

资源

• CATS API： https://docs.catsone.com/api/v3/
• FastMCP： https://gofastmcp.com/
• MCP协议： https://modelcontextprotocol.io/

许可证

为CATS API v3集成提供as-is。遵循CATS API的服务条款。

更新日志

2025-12-16-v2.0.0

• 全面覆盖API：从164个扩展到228个工具（+64个端点）
• 添加了缺失的关键功能：

- 列表管理（候选人/职位/公司/联系人列表-32个端点） - 状态管理（工作/公司/联系人状态-9个端点） - 缩略图（候选人/公司/联系人-6个端点） - 自定义字段详细信息（每个资源3个端点，共9个端点） - 工作历史CRUD（3个端点） - 公司电话（5个端点） - 公司部门（5个端点）

• 错误修正:

- 固定的 filter_candidates 分页（移至JSON正文） - 固定的 filter_jobs 分页（移至JSON正文）

• 现在涵盖了100%有文档记录的CATS API v3端点

2025-01-26-v1.0.0

• 带有工具集架构的初始版本
• 17套工具中的164个工具
• 通过CLI/环境动态加载
• 约82%的CATS API v3覆盖率
• 生产准备就绪