Recruitment Pipeline

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:

1. 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.

2. 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.

3. 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.

4. 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.