Initial upload with project structure, documentation, and CI/CD

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