cli/docs/mcp-integration.md

MCP Integration

The Core CLI includes a Model Context Protocol (MCP) server that provides file operations, RAG (Retrieval-Augmented Generation), metrics tracking, and process management tools for AI assistants like Claude Code.

Overview

MCP is a protocol that allows AI assistants to interact with external tools and services. The Core CLI's MCP server exposes a rich set of tools for:

• File Operations - Read, write, edit, delete files and directories
• RAG System - Semantic search using Qdrant + Ollama embeddings
• Metrics - Record and query application metrics
• Process Management - Start, stop, and monitor processes
• Language Detection - Detect programming languages
• WebSocket - Real-time communication
• WebView/CDP - Browser automation via Chrome DevTools Protocol

Quick Start

Start MCP Server

Stdio mode (for Claude Code):

core mcp serve

TCP mode:

MCP_ADDR=localhost:9999 core mcp serve

With workspace restriction:

core mcp serve --workspace /path/to/project

Configure in Claude Code

Add to your Claude Code MCP configuration (~/.claude/mcp_config.json):

{
  "mcpServers": {
    "core-mcp": {
      "command": "core",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

With workspace restriction:

{
  "mcpServers": {
    "core-mcp": {
      "command": "core",
      "args": ["mcp", "serve", "--workspace", "/home/user/projects/myapp"],
      "env": {}
    }
  }
}

Transport Modes

Stdio (Default)

Best for integration with Claude Code and other AI assistants that communicate via standard input/output.

core mcp serve

Pros:

• Simple setup
• Secure (no network exposure)
• Works with Claude Code out of the box

Cons:

• Single client only
• Process-coupled (client must manage server lifecycle)

TCP

Best for network-based integrations or when you need multiple clients.

MCP_ADDR=localhost:9999 core mcp serve

Pros:

• Multiple clients can connect
• Server runs independently
• Can connect from remote machines (if exposed)

Cons:

• Requires network configuration
• No built-in authentication (use firewall/SSH tunnel)
• More complex setup

Available Tools

File Operations

file_read

Read contents of a file.

Parameters:

• path (string, required) - File path to read

Example:

{
  "name": "file_read",
  "arguments": {
    "path": "/path/to/file.txt"
  }
}

file_write

Write content to a file (creates or overwrites).

Parameters:

• path (string, required) - File path to write
• content (string, required) - Content to write

Example:

{
  "name": "file_write",
  "arguments": {
    "path": "/path/to/file.txt",
    "content": "Hello, world!"
  }
}

file_edit

Edit a file by replacing old content with new content.

Parameters:

• path (string, required) - File path to edit
• old_content (string, required) - Content to find
• new_content (string, required) - Replacement content

Example:

{
  "name": "file_edit",
  "arguments": {
    "path": "/path/to/file.txt",
    "old_content": "old text",
    "new_content": "new text"
  }
}

file_delete

Delete a file.

Parameters:

• path (string, required) - File path to delete

file_rename

Rename or move a file.

Parameters:

• old_path (string, required) - Current file path
• new_path (string, required) - New file path

file_exists

Check if a file or directory exists.

Parameters:

• path (string, required) - Path to check

Returns:

• exists (boolean)
• is_dir (boolean)

dir_list

List contents of a directory.

Parameters:

• path (string, required) - Directory path
• recursive (boolean, optional) - Recursively list subdirectories

dir_create

Create a directory (including parent directories).

Parameters:

• path (string, required) - Directory path to create

RAG (Retrieval-Augmented Generation)

rag_ingest

Ingest documents into a collection for semantic search.

Parameters:

• collection (string, required) - Collection name
• documents (array, required) - Documents to ingest
  • id (string) - Document ID
  • text (string) - Document content
  • metadata (object, optional) - Additional metadata

Example:

{
  "name": "rag_ingest",
  "arguments": {
    "collection": "documentation",
    "documents": [
      {
        "id": "doc1",
        "text": "This is a documentation page about MCP",
        "metadata": {"type": "docs", "topic": "mcp"}
      }
    ]
  }
}

rag_query

Query a collection using semantic search.

Parameters:

• collection (string, required) - Collection name
• query (string, required) - Search query
• limit (integer, optional) - Maximum results (default: 5)

Returns: Array of matching documents with scores.

rag_collections

List all RAG collections.

Returns: Array of collection names and their document counts.

Metrics

metrics_record

Record a metric value.

Parameters:

• name (string, required) - Metric name
• value (number, required) - Metric value
• tags (object, optional) - Metric tags/labels
• timestamp (string, optional) - ISO 8601 timestamp

Example:

{
  "name": "metrics_record",
  "arguments": {
    "name": "api.requests",
    "value": 1,
    "tags": {"endpoint": "/api/users", "status": "200"}
  }
}

metrics_query

Query recorded metrics.

Parameters:

• name (string, optional) - Filter by metric name
• tags (object, optional) - Filter by tags
• from (string, optional) - Start time (ISO 8601)
• to (string, optional) - End time (ISO 8601)

Language Detection

lang_detect

Detect programming language from code or filename.

Parameters:

• content (string, optional) - Code content
• filename (string, optional) - Filename

Returns:

• language (string) - Detected language
• confidence (number) - Detection confidence (0-1)

lang_list

List all supported languages.

Returns: Array of supported language identifiers.

Process Management

process_start

Start a new process.

Parameters:

• id (string, required) - Process identifier
• command (string, required) - Command to execute
• args (array, optional) - Command arguments
• env (object, optional) - Environment variables
• cwd (string, optional) - Working directory

Example:

{
  "name": "process_start",
  "arguments": {
    "id": "build-process",
    "command": "go",
    "args": ["build", "-o", "bin/app"],
    "cwd": "/path/to/project"
  }
}

process_stop

Stop a running process (SIGTERM).

Parameters:

• id (string, required) - Process identifier

process_kill

Force kill a process (SIGKILL).

Parameters:

• id (string, required) - Process identifier

process_list

List all managed processes.

Returns: Array of process info (ID, command, status, PID).

process_output

Get output from a process.

Parameters:

• id (string, required) - Process identifier
• tail (integer, optional) - Number of recent lines

process_input

Send input to a process.

Parameters:

• id (string, required) - Process identifier
• input (string, required) - Input to send

WebSocket

ws_start

Start a WebSocket hub server.

Parameters:

• addr (string, optional) - Listen address (default: ":8080")

Returns:

• url (string) - WebSocket server URL

ws_info

Get WebSocket server information.

Returns:

• running (boolean)
• url (string)
• connections (integer)

WebView/CDP (Chrome DevTools Protocol)

webview_connect

Connect to Chrome/Chromium via CDP.

Parameters:

• url (string, required) - Debug URL (e.g., "http://localhost:9222")

webview_navigate

Navigate to a URL.

Parameters:

• url (string, required) - URL to navigate to

webview_click

Click an element.

Parameters:

• selector (string, required) - CSS selector

webview_type

Type text into an element.

Parameters:

• selector (string, required) - CSS selector
• text (string, required) - Text to type

webview_query

Query DOM for elements.

Parameters:

• selector (string, required) - CSS selector

Returns: Array of matching elements.

webview_console

Get console logs.

Returns: Array of console messages.

webview_eval

Evaluate JavaScript.

Parameters:

• script (string, required) - JavaScript code

Returns: Evaluation result.

webview_screenshot

Take a screenshot.

Parameters:

• full_page (boolean, optional) - Full page screenshot

Returns:

• data (string) - Base64-encoded PNG

webview_wait

Wait for condition.

Parameters:

• type (string, required) - Condition type ("selector", "navigation", "timeout")
• value (string/number, required) - Condition value

webview_disconnect

Disconnect from CDP.

Security Considerations

Workspace Restriction

Always use --workspace flag when exposing MCP server to AI assistants:

core mcp serve --workspace /path/to/safe/directory

This restricts file operations to the specified directory and its subdirectories, preventing the AI from accessing sensitive files outside the project.

File Operations

Without workspace restriction, the MCP server has full filesystem access. This is powerful but dangerous:

❌ Never run unrestricted in production:

core mcp serve  # Full filesystem access!

✅ Always restrict to project directory:

core mcp serve --workspace /home/user/projects/myapp

Network Exposure

When using TCP mode:

• Localhost only by default: MCP_ADDR=localhost:9999
• Never expose to public internet without authentication
• Use SSH tunnels for remote access
• Consider firewall rules to restrict access

Process Management

Processes started via process_start run with the same permissions as the MCP server. Be cautious when:

• Running as root/administrator
• Executing untrusted commands
• Exposing process management to external clients

Running as Daemon

Use the daemon command to run MCP server as a background service:

core daemon --mcp-transport tcp --mcp-addr :9100

With health endpoint:

core daemon --mcp-transport tcp --mcp-addr :9100 --health-addr :8080

Check health:

curl http://localhost:8080/health

Environment Variables

Variable	Description	Default
MCP_ADDR	TCP listen address	(stdio)
CORE_MCP_TRANSPORT	Transport mode (stdio, tcp)	stdio
CORE_MCP_ADDR	Alternative to MCP_ADDR	-
CORE_HEALTH_ADDR	Health check endpoint	-

Use Cases

1. Claude Code Integration

Enable Claude Code to read and modify files in your project:

{
  "mcpServers": {
    "core": {
      "command": "core",
      "args": ["mcp", "serve", "--workspace", "${workspaceFolder}"]
    }
  }
}

2. Semantic Code Search

Ingest codebase into RAG system for semantic search:

# Start MCP server
core mcp serve --workspace /path/to/project

# Ingest code (via AI assistant)
# Use: rag_ingest with collection="code" and documents from source files

# Query code
# Use: rag_query with query="authentication logic"

3. Build Automation

Monitor build processes with real-time output:

# Start MCP with WebSocket
# Use: ws_start
# Use: process_start with command="go build"
# Subscribe to process output via WebSocket

4. Web Automation Testing

Automate browser testing:

# Start Chrome with remote debugging:
# google-chrome --remote-debugging-port=9222

# Use CDP tools:
# webview_connect url="http://localhost:9222"
# webview_navigate url="https://example.com"
# webview_click selector="#login-button"
# webview_screenshot

Troubleshooting

Server Won't Start

Error: Port already in use

# Check what's using the port
lsof -i :9999

# Kill the process or use different port
MCP_ADDR=:9100 core mcp serve

Error: Permission denied

# Don't use privileged ports (<1024) without sudo
# Use high ports instead:
MCP_ADDR=:9999 core mcp serve

File Operations Fail

Error: File outside workspace

Make sure file paths are within the workspace:

# Workspace: /home/user/project
# ✅ OK: /home/user/project/src/main.go
# ❌ Fail: /etc/passwd

Error: Permission denied

Check file/directory permissions and MCP server user.

RAG Not Working

Error: Qdrant connection failed

Ensure Qdrant is running:

# Start Qdrant (Docker)
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

Error: Ollama not available

Ensure Ollama is running:

# Start Ollama
ollama serve

# Pull embedding model
ollama pull nomic-embed-text

Process Management Issues

Error: Process not found

List processes to verify ID:

{"name": "process_list"}

Error: Process already exists

Use unique process IDs or stop existing process first.

Performance Tips

1. Use workspace restriction - Reduces filesystem traversal overhead
2. Batch RAG ingestion - Ingest multiple documents in one call
3. Limit query results - Use limit parameter in rag_query
4. Process output streaming - Use WebSocket for real-time output
5. Reuse connections - Keep WebView CDP connection open for multiple operations

See Also

• CLI Reference - Complete command documentation
• Daemon Mode - Running MCP as a service
• RAG System - Detailed RAG documentation
• Environment Variables - Configuration options