MCP Recruitment Pipeline — Proof of Concept

An MCP server that turns a recruitment database into an AI-queryable pipeline. Instead of clicking through dashboards and writing filters, you ask Claude plain-English questions and it searches contractors, builds shortlists, drafts outreach, and books engagements — all through structured tool calls against a live PostgreSQL database. Built to demonstrate how service businesses can make their methodology accessible through Claude. Built by HelloCrossman.

What It Does

19 MCP tools that cover the full contractor recruitment lifecycle. Connect Claude to your database and ask:

"Show me available contractors in London with ISO 27001 under £600/day"
"What open jobs do we have that are marked as urgent?"
"Find matching contractors for the FinConnect pen testing role"
"Create a shortlist for the Meridian Bank compliance audit"
"Draft outreach for the top candidates — mention their PCI DSS experience"
"Book Sarah Chen for the senior auditor role at £575/day"
"Give me a full pipeline overview"
"Generate a PDF comparison of these three candidates"

Claude calls the right tools, chains them together, and handles the workflow end-to-end.

Screenshots

See the /screenshots directory for examples of Claude Desktop interacting with the server.

Architecture

Claude Desktop / Claude.ai
        │
        ▼
  MCP Server (Express.js)
  ├── Streamable HTTP  POST /mcp
  └── SSE              GET  /sse
        │
        ▼
  PostgreSQL
  ├── contractors  (50 enriched profiles)
  ├── jobs         (10 open roles)
  ├── shortlists + shortlist_items
  ├── engagements
  └── outreach_drafts

Stack: TypeScript · Node.js 20 · @modelcontextprotocol/sdk · Express · PostgreSQL · PDFKit · Google OAuth 2.1 · Vitest

MCP Tools

| Tool | What it does | Key parameters | |------|-------------|----------------| | search_contractors | Search by location, skills, certs, rate, clearance, free text | query, location, availability, certifications, skills, sector, max_rate, min_experience, clearance, limit | | get_contractor | Full profile by ID | id | | get_contractor_cv | Complete CV: work history, education, projects, languages | id | | list_jobs | List open roles with filters | status, sector, urgency, location, limit | | get_job | Full job details by ID | id | | find_matching_contractors | Auto-match contractors to a job's requirements | job_id, limit | | update_job_status | Move job through pipeline stages | id, status | | create_shortlist | Create a named shortlist for a role | name, description, role_title, client_name | | add_to_shortlist | Add contractor to shortlist with notes | shortlist_id, contractor_id, notes | | get_shortlist | View shortlist with all candidates | id | | list_shortlists | List all shortlists | status | | update_candidate_status | Track candidate through pipeline | shortlist_id, contractor_id, status | | draft_outreach | Save a personalised outreach email | contractor_id, shortlist_id, subject, body | | list_outreach | View outreach drafts | contractor_id, status | | book_contractor | Book contractor for a role | contractor_id, role_title, client_name, start_date, end_date, agreed_rate | | get_pipeline | Full recruitment pipeline overview | — | | generate_contractor_pdf | PDF report with full contractor CV | contractor_id | | generate_shortlist_pdf | PDF report of a shortlist | shortlist_id | | generate_comparison_pdf | Side-by-side PDF comparing 2–10 contractors | contractor_ids |

Quick Start

# 1. Clone the repo
git clone https://github.com/hellocrossman/mcp-recruitment-pipeline.git
cd mcp-recruitment-pipeline

# 2. Install dependencies
npm install

# 3. Set up PostgreSQL
#    Create a database and note the connection string.
#    On Replit, this is handled automatically.

# 4. Configure environment variables
cp .env.example .env
#    Edit .env with your DATABASE_URL and auth settings

# 5. Run database migrations
npm run migrate

# 6. Seed the database with sample data
npm run seed

# 7. Start the server
npm run dev

The server starts on port 5000 with 50 contractor profiles and 10 open roles.

Connect to Claude

Claude Desktop (SSE)

Add to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "recruitment": {
      "url": "https://your-deployment-url/sse",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

Claude.ai (Streamable HTTP)

In Claude.ai settings, add a custom MCP connector:

URL: https://your-deployment-url/mcp
Auth: Bearer token (your MCP_API_KEY)

Make It Your Own

This is a proof of concept — the structure is designed to be forked and adapted to any service domain. Key steps:

Define your data model. Replace contractors with your domain entities (candidates, properties, products, inventory). Update the migration files in migrations/ and the schema in src/db.ts.

Update the seed data. Edit src/seed.ts with realistic records for your domain. The current 50 contractor profiles show the level of enrichment that makes AI interactions useful.

Modify the tool handlers. Each function in src/tools.ts maps to one MCP tool. Rename them, change the query logic, add new tools. The pattern is always: validate input → build parameterised query → return structured result.

Deploy. Push to Replit, Railway, Fly.io, or any Node.js host with PostgreSQL access.

Project Structure

src/
  index.ts        Entry point — Express server, 19 MCP tool registrations
  types.ts        Shared TypeScript interfaces and constants
  db.ts           Database pool and schema initialization
  auth.ts         Google OAuth + API key middleware
  tools.ts        Query builders for all 16 data tools
  pdf.ts          PDF report generators (contractor CV, shortlist, comparison)
  seed.ts         50 contractor profiles + 10 sample jobs

migrations/       Numbered SQL migration files
scripts/          Utility scripts (migrate runner)
__tests__/        111 tests (unit + integration)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | DATABASE_URL | Yes | PostgreSQL connection string | | PORT | No | Server port (default: 5000) | | GOOGLE_CLIENT_ID | No | Google OAuth client ID for token verification | | MCP_API_KEY | No | API key for direct access without OAuth |

At least one auth method (GOOGLE_CLIENT_ID or MCP_API_KEY) is recommended for production.

Running Tests

npm test              # Run all 111 tests
npm run test:coverage # Run with coverage report
npm run test:watch    # Watch mode during development
npm run lint          # Type-check without emitting

Coverage: 100% on tool handlers, 90%+ on auth, 95%+ on database layer. Tests include unit tests with mocked DB, integration tests against real PostgreSQL, and edge cases for invalid inputs and SQL injection attempts.

License

MIT — see LICENSE.

Built By

HelloCrossman — We turn service businesses into agentic software.

MCP Recruitment Pipeline