From 81c4ef09a028b573e08b6ef5f5c2962133c234f2 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Thu, 5 Feb 2026 12:27:40 +0000 Subject: [PATCH] Initial upload with project structure, documentation, and CI/CD --- README.md | 296 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 294 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6418d0a..f6b72cb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,295 @@ -# mcp-server-cli +# MCP Server CLI -A CLI tool that creates a local Model Context Protocol (MCP) server for developers \ No newline at end of file +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