repohealth-cli/README.md

MCP Server CLI

A CLI tool that creates a local Model Context Protocol (MCP) server for developers, enabling custom tool definitions in YAML/JSON with built-in file operations, git commands, shell execution, and local LLM support for offline AI coding assistant integration.

Installation

pip install -e .

Or from source:

git clone <repository>
cd mcp-server-cli
pip install -e .

Quick Start

1. Initialize a configuration file:

mcp-server config init -o config.yaml

2. Start the server:

mcp-server server start --port 3000

3. The server will be available at http://127.0.0.1:3000

CLI Commands

Server Management

# Start the MCP server
mcp-server server start --port 3000 --host 127.0.0.1

# Check server status
mcp-server server status

# Health check
mcp-server health

Tool Management

# List available tools
mcp-server tool list

# Add a custom tool
mcp-server tool add path/to/tool.yaml

# Remove a custom tool
mcp-server tool remove tool_name

Configuration

# Show current configuration
mcp-server config show

# Generate a configuration file
mcp-server config init -o config.yaml

Configuration

Create a config.yaml file:

server:
  host: "127.0.0.1"
  port: 3000
  log_level: "INFO"

llm:
  enabled: false
  base_url: "http://localhost:11434"
  model: "llama2"

security:
  allowed_commands:
    - ls
    - cat
    - echo
    - git
  blocked_paths:
    - /etc
    - /root

Environment Variables

Variable	Description
MCP_PORT	Server port
MCP_HOST	Server host
MCP_LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)
MCP_LLM_URL	Local LLM base URL

Built-in Tools

File Operations

Tool	Description
file_tools	Read, write, list, search, glob files
read_file	Read file contents
write_file	Write content to a file
list_directory	List directory contents
glob_files	Find files matching a pattern

Git Operations

Tool	Description
git_tools	Git operations: status, log, diff, branch
git_status	Show working tree status
git_log	Show commit history
git_diff	Show changes between commits

Shell Execution

Tool	Description
shell_tools	Execute shell commands safely
execute_command	Execute a shell command

Custom Tools

Define custom tools in YAML:

name: my_tool
description: Description of the tool

input_schema:
  type: object
  properties:
    param1:
      type: string
      description: First parameter
      required: true
    param2:
      type: integer
      description: Second parameter
      default: 10
  required:
    - param1

annotations:
  read_only_hint: true
  destructive_hint: false

Or in JSON:

{
  "name": "example_tool",
  "description": "An example tool",
  "input_schema": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "The message to process",
        "required": true
      }
    },
    "required": ["message"]
  }
}

Local LLM Integration

Connect to local LLMs (Ollama, LM Studio, llama.cpp):

llm:
  enabled: true
  base_url: "http://localhost:11434"
  model: "llama2"
  temperature: 0.7
  max_tokens: 2048

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server": {
      "command": "mcp-server",
      "args": ["server", "start", "--port", "3000"]
    }
  }
}

Cursor Integration

Add to Cursor settings (JSON):

{
  "mcpServers": {
    "mcp-server": {
      "command": "mcp-server",
      "args": ["server", "start", "--port", "3000"]
    }
  }
}

Security Considerations

• Shell commands are whitelisted by default
• Blocked paths prevent access to sensitive directories
• Command timeout prevents infinite loops
• All operations are logged

API Reference

Endpoints

• GET /health - Health check
• GET /api/tools - List tools
• POST /api/tools/call - Call a tool
• POST /mcp - MCP protocol endpoint

MCP Protocol

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocol_version": "2024-11-05",
    "capabilities": {},
    "client_info": {"name": "client"}
  }
}

Example: Read a File

curl -X POST http://localhost:3000/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "read_file", "arguments": {"path": "/path/to/file.txt"}}'

Example: List Tools

curl http://localhost:3000/api/tools

License

MIT