0c27de4162
- Renamed all directories: OpenHarbor.MCP.* → Svrnty.MCP.* - Updated all namespaces in 179 C# files - Renamed 20 .csproj files and 3 .sln files - Updated 193 documentation references - Updated 33 references in main CODEX codebase - Updated Codex.sln with new paths - Build verified: 0 errors Preparing for extraction to standalone repositories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
189 lines
4.6 KiB
Markdown
189 lines
4.6 KiB
Markdown
# Adding CODEX MCP Server to Claude Code CLI
|
|
|
|
This guide shows how to integrate the CODEX MCP Server with Claude Code CLI (in WebStorm or standalone).
|
|
|
|
## Prerequisites
|
|
|
|
- .NET 8.0 SDK installed
|
|
- Claude Code CLI installed and configured
|
|
- Svrnty.MCP.Server cloned/copied to your system
|
|
|
|
## One-Time Setup
|
|
|
|
### 1. Build the CODEX MCP Server
|
|
|
|
```bash
|
|
cd /home/svrnty/codex/Svrnty.MCP.Server
|
|
dotnet build samples/CodexMcpServer/CodexMcpServer.csproj
|
|
```
|
|
|
|
### 2. Add to Claude Code CLI
|
|
|
|
```bash
|
|
# Add CODEX MCP server with HTTP transport
|
|
claude mcp add --transport stdio --scope user codex \
|
|
dotnet -- run --project /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
**Command Breakdown:**
|
|
- `--transport stdio` - Use stdin/stdout communication (required for .NET console apps)
|
|
- `--scope user` - Available across all projects for this user (alternatives: `local`, `project`)
|
|
- `codex` - The name of the MCP server (used in CLI commands)
|
|
- `dotnet -- run --project <path>` - Command to start the server
|
|
|
|
### 3. Verify Setup
|
|
|
|
```bash
|
|
# List all MCP servers
|
|
claude mcp list
|
|
|
|
# View CODEX server details
|
|
claude mcp get codex
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
codex:
|
|
Command: dotnet
|
|
Args: [run, --project, /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer]
|
|
Transport: stdio
|
|
Scope: user
|
|
```
|
|
|
|
## Usage in Claude Code CLI
|
|
|
|
### Interactive Mode
|
|
|
|
```bash
|
|
# Start Claude in interactive mode
|
|
claude
|
|
|
|
# Claude will automatically discover the CODEX tools
|
|
# You can now ask questions like:
|
|
# "Search CODEX for documents about neural networks"
|
|
# "List all documents in CODEX"
|
|
# "Get tags from CODEX"
|
|
```
|
|
|
|
### Project Mode (WebStorm)
|
|
|
|
When using Claude Code CLI in WebStorm, the CODEX MCP server is automatically available:
|
|
|
|
1. Open WebStorm
|
|
2. Open Claude Code panel
|
|
3. Ask Claude to search CODEX:
|
|
- "Search my CODEX knowledge base for information about MCP"
|
|
- "List recent documents from CODEX"
|
|
- "What tags are available in CODEX?"
|
|
|
|
## Available Tools
|
|
|
|
The CODEX MCP server exposes 6 tools:
|
|
|
|
| Tool | Description | Parameters |
|
|
|------|-------------|------------|
|
|
| `search_codex` | Semantic/keyword search | `query` (string) |
|
|
| `get_document` | Retrieve document by ID | `id` (string) |
|
|
| `list_documents` | List all documents with pagination | `page` (int), `pageSize` (int) |
|
|
| `search_by_tag` | Filter documents by tag | `tag` (string) |
|
|
| `get_document_sections` | Get document sections | `id` (string) |
|
|
| `list_tags` | List all available tags | None |
|
|
|
|
## Troubleshooting
|
|
|
|
### Server Not Responding
|
|
|
|
```bash
|
|
# Test the server manually
|
|
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | \
|
|
dotnet run --project /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
**Expected:** JSON response listing all 6 tools
|
|
|
|
### CODEX API Connection Errors
|
|
|
|
The tools will return errors if CODEX API is not running:
|
|
|
|
```
|
|
Error: Connection refused (localhost:5050)
|
|
```
|
|
|
|
**Solution:** Start your CODEX API service:
|
|
```bash
|
|
# Start CODEX API (adjust path as needed)
|
|
cd /path/to/CODEX
|
|
dotnet run --project src/Codex.Api
|
|
```
|
|
|
|
### Removing the Server
|
|
|
|
```bash
|
|
# Remove CODEX MCP server from CLI
|
|
claude mcp remove codex
|
|
|
|
# Verify removal
|
|
claude mcp list
|
|
```
|
|
|
|
## Testing End-to-End
|
|
|
|
Run the test script to verify everything works:
|
|
|
|
```bash
|
|
cd /home/svrnty/codex/Svrnty.MCP.Server
|
|
python3 test_mcp_server.py
|
|
```
|
|
|
|
**Expected:** All 10 tests should pass (tools return proper JSON-RPC responses)
|
|
|
|
## Advanced Configuration
|
|
|
|
### Scopes
|
|
|
|
- **user** (recommended): Available globally for your user account
|
|
- **local**: Available only in current directory
|
|
- **project**: Available only in current project
|
|
|
|
```bash
|
|
# Change scope
|
|
claude mcp remove codex
|
|
claude mcp add --transport stdio --scope project codex \
|
|
dotnet -- run --project /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
### Using Absolute Paths
|
|
|
|
For reliability, use absolute paths:
|
|
|
|
```bash
|
|
claude mcp add --transport stdio --scope user codex \
|
|
/usr/bin/dotnet -- run --project /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. **Start CODEX API** (if you want to test with real data):
|
|
```bash
|
|
cd /path/to/CODEX
|
|
dotnet run --project src/Codex.Api
|
|
```
|
|
|
|
2. **Ask Claude to search CODEX:**
|
|
```
|
|
"Search CODEX for documents about clean architecture"
|
|
```
|
|
|
|
3. **Explore other tools:**
|
|
```
|
|
"List all tags in CODEX"
|
|
"Get document sections for document ID xyz123"
|
|
```
|
|
|
|
## Reference
|
|
|
|
- [Claude Code CLI Documentation](https://docs.claude.com/en/docs/claude-code)
|
|
- [Model Context Protocol Spec](https://modelcontextprotocol.io)
|
|
- [Svrnty.MCP README](README.md)
|
|
- [CODEX Documentation](../CODEX/README.md)
|