mcp-server-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.

## Features

- **MCP Protocol Support**: Full Model Context Protocol server implementation
- **Built-in Tools**: File operations, git commands, and shell execution
- **Custom Tools**: Define your own tools in YAML/JSON format
- **Local LLM Integration**: Connect to Ollama, LM Studio, or other local LLMs
- **Security**: Whitelisted commands and blocked paths for safe execution
- **CLI Interface**: Easy-to-use command-line interface

## Installation

```bash
pip install mcp-server-cli
```

Or from source:

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/mcp-server-cli.git
cd mcp-server-cli
pip install -e .
```

## Quick Start

1. Initialize a configuration file:

```bash
mcp-server config init -o config.yaml
```

2. Start the server:

```bash
mcp-server server start --port 3000
```

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

## CLI Commands

### Server Management

```bash
# 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

```bash
# 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

```bash
# Show current configuration
mcp-server config show

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

## Configuration

Create a `config.yaml` file:

```yaml
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:

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

```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):

```yaml
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`:

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

## Cursor Integration

Add to Cursor settings (JSON):

```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

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

### Example: Read a File

```bash
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

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

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linting
ruff check .
```

## License

MIT License