Svrnty 516e1479c6 docs: comprehensive AI coding assistant research and MCP-first implementation plan

Research conducted on modern AI coding assistants (Cursor, GitHub Copilot, Cline,
Aider, Windsurf, Replit Agent) to understand architecture patterns, context management,
code editing workflows, and tool use protocols.

Key Decision: Pivoted from building full CLI (40-50h) to validation-driven MCP-first
approach (10-15h). Build 5 core CODEX MCP tools that work with ANY coding assistant,
validate adoption over 2-4 weeks, then decide on full CLI if demand proven.

Files:
- research/ai-systems/modern-coding-assistants-architecture.md (comprehensive research)
- research/ai-systems/codex-coding-assistant-implementation-plan.md (original CLI plan, preserved)
- research/ai-systems/codex-mcp-tools-implementation-plan.md (approved MCP-first plan)
- ideas/registry.json (updated with approved MCP tools proposal)

Architech Validation: APPROVED with pivot to MCP-first approach
Human Decision: Approved (pragmatic validation-driven development)

Next: Begin Phase 1 implementation (10-15 hours, 5 core MCP tools)

🤖 Generated with CODEX Research System

Co-Authored-By: The Archivist <archivist@codex.svrnty.io>
Co-Authored-By: The Architech <architech@codex.svrnty.io>
Co-Authored-By: Mathias Beaulieu-Duncan <mat@svrnty.io>

2025-10-22 21:00:34 -04:00

4.6 KiB

Raw Blame History

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
OpenHarbor.MCP.Server cloned/copied to your system

One-Time Setup

1. Build the CODEX MCP Server

cd /home/svrnty/codex/OpenHarbor.MCP.Server
dotnet build samples/CodexMcpServer/CodexMcpServer.csproj

2. Add to Claude Code CLI

# Add CODEX MCP server with HTTP transport
claude mcp add --transport stdio --scope user codex \
  dotnet -- run --project /home/svrnty/codex/OpenHarbor.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

# 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/OpenHarbor.MCP.Server/samples/CodexMcpServer]
  Transport: stdio
  Scope: user

Usage in Claude Code CLI

Interactive Mode

# 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:

Open WebStorm
Open Claude Code panel
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

# Test the server manually
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | \
  dotnet run --project /home/svrnty/codex/OpenHarbor.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:

# Start CODEX API (adjust path as needed)
cd /path/to/CODEX
dotnet run --project src/Codex.Api

Removing the Server

# 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:

cd /home/svrnty/codex/OpenHarbor.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

# Change scope
claude mcp remove codex
claude mcp add --transport stdio --scope project codex \
  dotnet -- run --project /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer

Using Absolute Paths

For reliability, use absolute paths:

claude mcp add --transport stdio --scope user codex \
  /usr/bin/dotnet -- run --project /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer

Next Steps

Start CODEX API (if you want to test with real data):

cd /path/to/CODEX
dotnet run --project src/Codex.Api

Ask Claude to search CODEX:

"Search CODEX for documents about clean architecture"

Explore other tools:

"List all tags in CODEX"
"Get document sections for document ID xyz123"

4.6 KiB Raw Blame History