Skip to main content
Glama
CoderSwap MCP Server
by njlnaet

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:

  1. Create a project:

    Use coderswap_create_project with name "AI Research"
  2. Ingest research content:

    Use coderswap_research_ingest with URLs:
    - https://arxiv.org/abs/2103.00020
    - https://openai.com/research/gpt-4
  3. Monitor progress (Claude keeps polling until complete):

    Use coderswap_get_job_status to check ingestion
  4. Search the knowledge base:

    Use coderswap_search with query "transformer architecture"
  5. Optional: run a quick multi-query smoke test:

    Use coderswap_test_search_quality with test queries or run_full_suite: true
  6. 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! 🚀

Available Tools

8 tools
coderswap_create_projectCreate CoderSwap ProjectB

Create a new vector search project in CoderSwap

Inputs: name (required), description. Returns: name, status, project_id

coderswap_get_job_statusGet CoderSwap Job StatusB

Check the status of a research ingestion job

Inputs: job_id (required). Returns: state, job_id, failed_count, crawled_count

coderswap_get_project_statsGet CoderSwap Project StatsC

Get statistics and information about a specific project

Inputs: project_id (required). Returns: name, doc_count, created_at, project_id

coderswap_list_projectsList CoderSwap ProjectsB

List all CoderSwap projects available to your API key

Inputs: no named parameters. Returns: count, projects

coderswap_log_session_noteLog Session NoteC

Record lightweight ingestion summary for session continuity (non-DSL)

Inputs: project_id (required), summary_text (required), job_id, ingestion_metrics, +1 more. Returns: note_id, timestamp, project_id

coderswap_research_ingestCoderSwap Research IngestC

Submit research summary and URLs for web crawling, chunking, embedding, and optional DSL generation

Inputs: project_id (required), urls (required), research_summary, intent, +2 more. Returns: job_id, status, project_id

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. The tools cover different aspects of the workflow: project management (create, list, get stats), job monitoring (get job status), ingestion (research_ingest, log_session_note), and search operations (search, validate_search). There is no overlap in functionality that would cause misselection.

    Naming Consistency5/5

    All tools follow a consistent 'coderswap_verb_noun' pattern throughout, using snake_case uniformly. The verbs are descriptive and appropriate for each action (e.g., create_project, get_job_status, list_projects), making the naming highly predictable and readable.

    Tool Count5/5

    With 8 tools, the count is well-scoped for a vector search project management server. Each tool earns its place by covering essential operations: project lifecycle (create, list, get stats), ingestion workflows (research_ingest, log_session_note), job monitoring, and search functionality (search, validate). This is neither too sparse nor bloated.

    Completeness4/5

    The tool set provides comprehensive coverage for core CoderSwap workflows, including project CRUD, ingestion, and search. A minor gap exists in the lack of update or delete operations for projects, which might limit full lifecycle management, but agents can likely work around this given the server's focus on ingestion and search.

    Related MCP Connectors