@coderswap/mcp-server

CoderSwap MCP Server

Model Context Protocol (MCP) server that lets Claude (and any MCP-aware agent) stand up a topic-specific knowledge base end-to-end—project creation, ingestion, progress tracking, search validation, and lightweight session notes—without exposing low-level APIs.

Features

• 🚀 Create and list vector-search projects
• 📚 Ingest research summaries + URLs with auto-crawling, chunking, and embedding
• 🧠 Auto-ingest curated sources (crawl → chunk → embed) with relevance tuning handled by the CoderSwap platform team
• 🔍 Execute hybrid semantic search with intent-aware ranking
• 📊 Monitor ingestion jobs, capture blocked sources, and run quick search-quality spot checks
• ✨ Rich, formatted output optimized for AI agents

Installation

cd packages/mcp-server
npm install
npm run build

Configuration

Set the following environment variables before launching the server:

• CODERSWAP_BASE_URL (default: http://localhost:8000)
• CODERSWAP_API_KEY (required)
• DEBUG (optional: set to true for detailed logging)

Running

Development (Local Backend)

# Set environment variables
export CODERSWAP_BASE_URL=http://localhost:8000
export CODERSWAP_API_KEY=cs_dev_nmVDJupuxflYYWd34HiRxbtxONul3hv1_f981

# Run the server
npm start

Claude Desktop Configuration

Update your Claude Desktop config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Local Development:

{
  "mcpServers": {
    "coderswap": {
      "command": "node",
      "args": ["C:/Users/tayav/CascadeProjects/CoderSwapIO/packages/mcp-server/dist/index.js"],
      "env": {
        "CODERSWAP_BASE_URL": "http://localhost:8000",
        "CODERSWAP_API_KEY": "cs_dev_nmVDJupuxflYYWd34HiRxbtxONul3hv1_f981"
      }
    }
  }
}

Production:

{
  "mcpServers": {
    "coderswap": {
      "command": "npx",
      "args": ["-y", "@coderswap/mcp-server"],
      "env": {
        "CODERSWAP_BASE_URL": "https://api.coderswap.ai",
        "CODERSWAP_API_KEY": "your_production_api_key"
      }
    }
  }
}

Available Tools

Project Management

• coderswap_create_project – Create a new vector search project
• coderswap_list_projects – List accessible projects with document counts
• coderswap_get_project_stats – Pull basic stats (created_at, document totals)

Research & Ingestion

• coderswap_research_ingest – Crawl, chunk, and embed vetted URLs (advanced tuning is managed by the platform team)
• coderswap_get_job_status – Poll ingestion job progress, crawl counts, blocked domains

Search & Validation

• coderswap_search – Execute hybrid semantic search with ranked snippets
• coderswap_test_search_quality – Run quick multi-query smoke tests (or a predefined suite) to gauge relevance

Session Continuity

• coderswap_log_session_note – Record lightweight summaries (job_id, ingestion metrics, follow-ups) so humans stay in the loop

Guardrails & Security

• The server loads mcp_starter_prompt.yaml at startup and injects it as a non-removable system prompt.
• Startup fails if the prompt is missing, invalid, or tampered with (hash mismatch).
• Advanced tuning endpoints are intentionally omitted; when deeper adjustments are required, Claude guides users to loop in the CoderSwap platform team.
• All operations must go through the MCP tools; direct HTTP/DB access is disallowed.

Each tool:

• ✅ Validates inputs with Zod schemas
• ✅ Returns both structured data and AI-friendly text summaries
• ✅ Includes comprehensive error handling
• ✅ Logs operations for debugging (when DEBUG=true)

Example Usage

Autonomous Research Workflow

Claude can execute this workflow autonomously:

• Create a project:

  Use coderswap_create_project with name "AI Research"
  

• Ingest research content:

  Use coderswap_research_ingest with URLs:
  - https://arxiv.org/abs/2103.00020
  - https://openai.com/research/gpt-4
  

• Monitor progress (Claude keeps polling until complete):

  Use coderswap_get_job_status to check ingestion
  

• Search the knowledge base:

  Use coderswap_search with query "transformer architecture"
  

• Optional: run a quick multi-query smoke test:

  Use coderswap_test_search_quality with test queries or run_full_suite: true
  

• Leave yourself a handoff note (e.g., sources blocked, next steps):

  Use coderswap_log_session_note with project_id "proj_123",
  summary_text "Ingested 9/10 sources; FDA site blocked by robots.txt. Run follow-up after manual download."
  job_id "job_456"
  ingestion_metrics {"sources_succeeded": 9, "sources_failed": 1}
  

Output Format

Search results are formatted with rich details:

Found 5 result(s) for: "hybrid search"

🥇 Score: 85.2%
   About hybrid search | Vertex AI
   Vector Search supports hybrid search...

🥈 Score: 72.1%
   Hybrid Search | Weaviate
   Hybrid search combines semantic and keyword...

🥉 Score: 68.4%
   ...

Debugging

Enable debug logging:

export DEBUG=true
npm start

Logs are written to stderr and include:

• Timestamps
• Operation details
• Error messages with context

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (for development)
npm run dev

Architecture

Claude Desktop → MCP Server (stdio) → CoderSwap Backend API → Oracle ADW 23ai
                  ↓
            - Tool validation (Zod)
            - Error handling
            - Response formatting

With the MCP server, Claude can autonomously build, test, and optimize vector knowledge bases in minutes! 🚀