Janus RAG MCP Server

@tsi-janus/janus-rag-mcp-server exposes Janus-RAG search and working-set APIs over the Model Context Protocol so external editors can call the same tooling the runner uses.

Quick Start

npx -y @tsi-janus/janus-rag-mcp-server

MCP Client Configuration

Roo Code (Claude/VS Code)

Add an entry to the Roo Code MCP config (usually .roocode/config.json or via Roo Code settings):

{
  "mcpServers": {
    "janus-rag": {
      "command": "npx",
      "args": ["-y", "@tsi-janus/janus-rag-mcp-server"],
      "env": {
        "JANUS_RAG_BASE_URL": "http://localhost:8081",
        "JANUS_RAG_WORKSPACE": "your-workspace-id",
        "JANUS_RAG_AUTH_TOKEN": "<your-token-here>",
        "JANUS_RAG_TIMEOUT_MS": "60000"
      }
    }
  }
}

GitHub Copilot (VS Code)

Add a server entry in your VS Code settings.json:

{
  "copilot.mcp.servers": {
    "janus-rag": {
      "command": "npx",
      "args": ["-y", "@tsi-janus/janus-rag-mcp-server"],
      "env": {
        "JANUS_RAG_BASE_URL": "http://localhost:8081",
        "JANUS_RAG_WORKSPACE": "your-workspace-id",
        "JANUS_RAG_AUTH_TOKEN": "<your-token-here>",
        "JANUS_RAG_TIMEOUT_MS": "60000"
      }
    }
  }
}

Authentication

MCP Workspace Tokens (Recommended)

Static API keys tied to specific workspaces - perfect for MCP clients:

1. Create in Janus Manager UI:

   • Navigate to your project in Janus Manager
   • Select the branch you want to use
   • Go to "MCP workspace tokens" section
   • Click "Create Token"
   • Provide a descriptive label (e.g., "IDE Integration", "RooCode")
   • Copy the generated token (shown only once!)

2. Use the token in your MCP client configuration (see examples above).

Benefits:

• ✅ Never expire - set it once and forget
• ✅ Per-workspace access control
• ✅ Revocable through the UI without affecting other tokens
• ✅ Audit trail - tracks when tokens are used
• ✅ User-associated - you can see who created each token

Workspace ID: The workspace ID is automatically generated when you create a token and is shown in the Janus Manager UI. It typically follows the pattern: ns{namespaceId}_p{projectId}_{branchName}.

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | JANUS_RAG_BASE_URL | ✅ | Base URL for the Janus-RAG HTTP API (e.g., http://localhost:8081). | | JANUS_RAG_WORKSPACE | ✅ | Workspace ID for your project/branch. | | JANUS_RAG_AUTH_TOKEN | ✅ | MCP workspace token for authentication. | | JANUS_RAG_TIMEOUT_MS | ❌ (default: 8000) | HTTP timeout when calling Janus-RAG. | | JANUS_RAG_AUTH_USER / JANUS_RAG_AUTH_PASSWORD | ❌ | Basic-auth credentials (alternative to token). |

[!NOTE] The server chooses bearer auth when JANUS_RAG_AUTH_TOKEN is present, otherwise basic auth when both username and password are provided.

Available Tools

The server exposes the following MCP tools:

| Tool | Description | | --- | --- | | janus_query | Semantic query against the graph and document store. | | janus_build_working_set | Build a bounded working set for edits/impact/refactors. | | janus_get_working_set | Retrieve an existing working set by id. | | janus_impact_plan | Estimate blast radius and suggested tests for changed files/symbols. | | janus_ingest_files | Push ad-hoc file contents into Janus-RAG for immediate availability. |

These map directly onto the Janus-RAG HTTP endpoints with the workspace and auth values provided via environment.

Troubleshooting

"fetch failed" or SSL Certificate Errors

If you're connecting to a Janus instance with a self-signed certificate (e.g., https://localhost:8081), add NODE_TLS_REJECT_UNAUTHORIZED to your env config:

Roo Code (.roocode/config.json):

{
  "mcpServers": {
    "janus-rag": {
      "command": "npx",
      "args": ["-y", "@tsi-janus/janus-rag-mcp-server"],
      "env": {
        "JANUS_RAG_BASE_URL": "https://localhost:8081",
        "JANUS_RAG_WORKSPACE": "your-workspace-id",
        "JANUS_RAG_AUTH_TOKEN": "<token>",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

GitHub Copilot (settings.json):

{
  "copilot.mcp.servers": {
    "janus-rag": {
      "command": "npx",
      "args": ["-y", "@tsi-janus/janus-rag-mcp-server"],
      "env": {
        "JANUS_RAG_BASE_URL": "https://localhost:8081",
        "JANUS_RAG_WORKSPACE": "your-workspace-id",
        "JANUS_RAG_AUTH_TOKEN": "<token>",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

[!WARNING] Setting NODE_TLS_REJECT_UNAUTHORIZED=0 disables SSL certificate verification. Only use this in development environments with self-signed certificates. For production, use proper SSL certificates.

Verify Janus Manager is Running

Check that the Janus manager service is accessible:

# Test HTTP connection
curl http://localhost:8081/actuator/health

# Test HTTPS connection (with SSL)
curl -k https://localhost:8081/actuator/health

Check MCP Server Logs

The MCP server logs to stderr (which doesn't interfere with the stdio protocol). Check your MCP client's logs to see configuration and error details.

Development

See CONTRIBUTING.md for local development, building from source, and publishing instructions.

License

See the repository license file.