README.md•5.88 kB
# 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
```bash
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)
```bash
# 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:
```json
{
"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:
```json
{
"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:
```bash
export DEBUG=true
npm start
```
Logs are written to stderr and include:
- Timestamps
- Operation details
- Error messages with context
## Development
```bash
# 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!** 🚀