CATS MCP Server

# CATS MCP Server - Core Infrastructure Complete **Status**: READY FOR TOOLSET INTEGRATION **File**: `/home/vanman2025/Projects/ai-dev-marketplace/cats-mcp-server/server.py` **Date**: 2025-10-26 ## Overview The core infrastructure for the CATS MCP server has been successfully created with a dynamic toolset loading system. The server is now ready to import and load the three toolset modules that will be created by other agents. ## Core Components ### 1. Configuration System ```python # Environment variables CATS_API_BASE_URL = os.getenv("CATS_API_BASE_URL", "https://api.catsone.com/v3") CATS_API_KEY = os.getenv("CATS_API_KEY", "") # Toolset definitions DEFAULT_TOOLSETS = ['candidates', 'jobs', 'pipelines', 'context', 'tasks'] ALL_TOOLSETS = DEFAULT_TOOLSETS + [ 'companies', 'contacts', 'activities', 'portals', 'work_history', 'tags', 'webhooks', 'users', 'triggers', 'attachments', 'backups', 'events' ] ``` ### 2. API Request Handler - `make_request()`: Async function for authenticated CATS API calls - Supports GET, POST, PUT, PATCH, DELETE methods - Automatic error handling and authentication - Configurable timeout (30 seconds) ### 3. Toolset Loading System ```python def load_toolsets(toolsets: Set[str]): """Load specified toolsets dynamically""" # Imports from three modules: # - toolsets_default.py (5 toolsets, 89 tools) # - toolsets_recruiting.py (5 toolsets, 52 tools) # - toolsets_data.py (7 toolsets, 21 tools) ``` **Loading Logic:** - Checks for each toolset name or 'all' - Calls corresponding `register_*_tools()` function - Prints confirmation for each loaded toolset - Reports total count ### 4. CLI Interface ```bash # List available toolsets python server.py --list-toolsets # Load default toolsets (candidates, jobs, pipelines, context, tasks) python server.py # Load specific toolsets python server.py --toolsets candidates,jobs # Load all 162 tools python server.py --toolsets all # Use environment variable export CATS_TOOLSETS='candidates,companies' python server.py ``` ## Toolset Organization ### DEFAULT Toolsets (89 tools) Loaded automatically if no toolsets specified: - **candidates** (28 tools) - Core recruiting functions - **jobs** (40 tools) - Job management - **pipelines** (13 tools) - Workflow management - **context** (3 tools) - Site/user information - **tasks** (5 tools) - Task management ### RECRUITING Toolsets (52 tools) Extended recruiting functionality: - **companies** (18 tools) - **contacts** (18 tools) - **activities** (6 tools) - **portals** (8 tools) - **work_history** (3 tools) ### DATA & CONFIG Toolsets (21 tools) System configuration and data management: - **tags** (2 tools) - **webhooks** (4 tools) - **users** (2 tools) - **triggers** (2 tools) - **attachments** (4 tools) - **backups** (3 tools) - **events** (5 tools) ## Expected Imports The server expects these three modules to be created by other agents: ### 1. toolsets_default.py Must export: - `register_candidates_tools()` - `register_jobs_tools()` - `register_pipelines_tools()` - `register_context_tools()` - `register_tasks_tools()` ### 2. toolsets_recruiting.py Must export: - `register_companies_tools()` - `register_contacts_tools()` - `register_activities_tools()` - `register_portals_tools()` - `register_work_history_tools()` ### 3. toolsets_data.py Must export: - `register_tags_tools()` - `register_webhooks_tools()` - `register_users_tools()` - `register_triggers_tools()` - `register_attachments_tools()` - `register_backups_tools()` - `register_events_tools()` ## Integration Pattern Each toolset registration function should follow this pattern: ```python def register_candidates_tools(): """Register all candidate-related tools""" from server import mcp, make_request @mcp.tool() async def list_candidates(per_page: int = 25, page: int = 1): """List candidates. GET /candidates""" return await make_request("GET", "/candidates", params={"per_page": per_page, "page": page}) # ... more tools ... ``` ## Features 1. **Selective Loading**: Load only the toolsets you need 2. **Environment Control**: Use `CATS_TOOLSETS` env var for deployment configs 3. **CLI Override**: Command-line args take precedence over env vars 4. **Validation**: Invalid toolset names are caught and reported 5. **Progress Feedback**: Real-time loading confirmations 6. **Help System**: `--list-toolsets` shows all available options ## Next Steps The following agents should create the toolset modules: 1. **Agent 1**: Create `toolsets_default.py` with 5 toolsets (89 tools) 2. **Agent 2**: Create `toolsets_recruiting.py` with 5 toolsets (52 tools) 3. **Agent 3**: Create `toolsets_data.py` with 7 toolsets (21 tools) ## Testing Once all toolset modules are created, test with: ```bash # Test help system python server.py --list-toolsets # Test default loading python server.py # Should load 5 DEFAULT toolsets # Test specific toolsets python server.py --toolsets candidates,companies # Test all toolsets python server.py --toolsets all # Should load all 162 tools ``` ## File Location **Absolute Path**: `/home/vanman2025/Projects/ai-dev-marketplace/cats-mcp-server/server.py` --- **Status**: Core infrastructure complete and ready for toolset integration **Total Lines**: 242 **Key Functions**: 2 (make_request, load_toolsets) **Supported Toolsets**: 17 **Total Tools Target**: 162