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! 🚀