CATS MCP Server

# CATS Recruiting Toolsets - Quick Start Guide ## Installation (3 Steps) ### 1. Verify Files ```bash cd /home/vanman2025/Projects/ai-dev-marketplace/cats-mcp-server ls -l toolsets_recruiting.py # Should exist (40KB) ``` ### 2. Import and Register Add to your `server.py`: ```python from toolsets_recruiting import register_all_recruiting_toolsets # After defining mcp and make_request register_all_recruiting_toolsets(mcp, make_request) ``` ### 3. Start Server ```bash python server.py # Server runs on http://localhost:8000 ``` ## What You Get (64 Tools) ### Companies (22) ```python # Main list_companies(), get_company(), create_company() update_company(), delete_company() search_companies(), filter_companies() # Sub-resources list_company_activities(), create_company_activity() list_company_contacts() list_company_departments(), create_company_department() list_company_tags(), attach_company_tags() ``` ### Contacts (25) ```python # Main list_contacts(), get_contact(), create_contact() update_contact(), delete_contact() search_contacts(), filter_contacts() # Sub-resources list_contact_emails(), create_contact_email() list_contact_phones(), create_contact_phone() list_contact_activities(), create_contact_activity() list_contact_tags(), attach_contact_tags() ``` ### Activities (6) ```python list_activities(), get_activity() update_activity(), delete_activity() search_activities(), filter_activities() ``` ### Portals (8) ```python list_portals(), get_portal() list_portal_jobs() publish_job_to_portal(), unpublish_job_from_portal() submit_job_application() ``` ### Work History (3) ```python get_work_history() update_work_history() delete_work_history() ``` ## Quick Examples ### Create Company ```python company = await create_company( name="TechCorp Inc.", website="https://techcorp.com", city="San Francisco", state="CA" ) ``` ### Add Contact ```python contact = await create_contact( first_name="Jane", last_name="Smith", email="jane@techcorp.com", company_id=company["id"], title="VP Engineering" ) ``` ### Log Activity ```python await create_company_activity( company_id=company["id"], activity_type="meeting", description="Kickoff call completed" ) ``` ### Publish to Portal ```python await publish_job_to_portal( portal_id=123, job_id=456 ) ``` ## File Reference | File | Size | Purpose | |------|------|---------| | `toolsets_recruiting.py` | 40KB | Main implementation (64 tools) | | `RECRUITING_TOOLSETS_SUMMARY.md` | 10KB | Complete documentation | | `RECRUITING_WORKFLOW_EXAMPLES.md` | 16KB | 9 complete workflows | | `INTEGRATION_EXAMPLE.py` | 2.8KB | Working integration example | | `DELIVERY_RECRUITING_TOOLSETS.md` | 9.2KB | Delivery summary | ## Common Operations ### Pagination ```python # Get all companies across multiple pages page = 1 all_companies = [] while True: batch = await list_companies(per_page=100, page=page) all_companies.extend(batch["companies"]) if len(batch["companies"]) < 100: break page += 1 ``` ### Search ```python # Simple search results = await search_companies(query="Tech") # Advanced filter results = await filter_companies( filters={"city": "San Francisco", "state": "CA"}, per_page=50 ) ``` ### Tags ```python # Replace all tags await replace_company_tags(company_id, [101, 102, 103]) # Add tags (additive) await attach_company_tags(company_id, [104, 105]) # Remove tags await delete_company_tags(company_id, [102]) ``` ## Testing ### Syntax Check ```bash python3 -m py_compile toolsets_recruiting.py # Should succeed without errors ``` ### Import Test ```bash python3 -c "from toolsets_recruiting import *; print('✓ OK')" ``` ### Integration Test ```bash python3 INTEGRATION_EXAMPLE.py # Should start server on port 8000 ``` ## Documentation - **Summary**: `RECRUITING_TOOLSETS_SUMMARY.md` - **Workflows**: `RECRUITING_WORKFLOW_EXAMPLES.md` - **Integration**: `INTEGRATION_EXAMPLE.py` - **Delivery**: `DELIVERY_RECRUITING_TOOLSETS.md` ## Support ### Tool Naming Pattern - List: `list_{resource}` (e.g., `list_companies`) - Get: `get_{resource}` (e.g., `get_company`) - Create: `create_{resource}` (e.g., `create_company`) - Update: `update_{resource}` (e.g., `update_company`) - Delete: `delete_{resource}` (e.g., `delete_company`) - Sub-resource: `{action}_{parent}_{child}` (e.g., `list_company_contacts`) ### Activity Types - `email` - Email communication - `meeting` - Meeting/call scheduled - `call_talked` - Successful call - `call_lvm` - Left voicemail - `call_missed` - Missed call - `text_message` - SMS/text - `other` - Other activity ### Error Handling ```python from server import CATSAPIError try: company = await create_company(name="Test") except CATSAPIError as e: print(f"Error: {e}") ``` ## Production Checklist - [ ] Import `register_all_recruiting_toolsets` in server.py - [ ] Call registration function after `mcp` and `make_request` defined - [ ] Set `CATS_API_KEY` in environment variables - [ ] Test with actual CATS API - [ ] Verify all tools accessible via MCP - [ ] Deploy server ## Quick Stats - **Total Tools**: 64 - **Total Endpoints**: 64 unique API endpoints - **Python Version**: 3.10+ - **Dependencies**: fastmcp, httpx, typing - **Status**: Production Ready ✓ --- **Need Help?** - See `RECRUITING_TOOLSETS_SUMMARY.md` for complete reference - See `RECRUITING_WORKFLOW_EXAMPLES.md` for usage examples - Check `INTEGRATION_EXAMPLE.py` for working code