# Mnevis MCP Server

> ⚠️ **This is an experiment.**

A **lightweight, zero-dependency** Python MCP server that exposes a single `do_everything` tool.
Any AI agent that supports MCP can use it to offload **all** language-model work to a local
OpenAI-compatible endpoint.

---

## How it works

```
AI Agent
    │
    │  MCP stdio (JSON-RPC 2.0)
    ▼
mnevis  server.py
    │
    │  HTTP POST /v1/chat/completions
    ▼
Local LLM  (Ollama, LM Studio, llama.cpp, vLLM, …)
```

The agent calls the `do_everything` tool with a `prompt` (and optional `system` instruction).  
The server forwards the request to the local LLM using the standard OpenAI chat-completions API  
and returns the model's response to the agent.

The tool description is worded so that any LLM automatically understands it should **delegate  
every task** to the tool instead of reasoning on its own.

---

## Requirements

- Python **3.11+**
- No third-party packages — uses the standard library only (`urllib`, `json`, `sys`, `os`)
- A running local LLM that exposes a `/v1/chat/completions` endpoint  

---

## Configuration

All settings are read from **environment variables** at startup:

| Variable          | Default                 | Description                                    |
|-------------------|-------------------------|------------------------------------------------|
| `MNEVIS_URL`      | `http://localhost`      | Base URL of the local LLM server               |
| `MNEVIS_PORT`     | `11434`                 | Port the LLM server listens on                 |
| `MNEVIS_MODEL`    | `llama3`                | Model name to pass in the request              |
| `MNEVIS_API_KEY`  | _(empty)_               | Optional API key (sent as `Bearer` token)      |
 | `MNEVIS_TIMEOUT`  | `120`                   | Request timeout in seconds for the LLM HTTP call |
 | `MNEVIS_LOGLEVEL` | `INFO`                  | Logging level for server diagnostics (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

### Examples

**Ollama (default port 11434):**
```bash
MNEVIS_MODEL=llama3 python server.py
```

**LM Studio (default port 1234):**
```bash
MNEVIS_URL=http://localhost MNEVIS_PORT=1234 MNEVIS_MODEL=lmstudio-community/Meta-Llama-3-8B-Instruct python server.py
```

**vLLM with API key:**
```bash
MNEVIS_URL=http://my-gpu-box MNEVIS_PORT=8000 MNEVIS_MODEL=mistral-7b MNEVIS_API_KEY=secret python server.py
```

---

## Running the server

The server communicates over **stdio** (JSON-RPC 2.0), so it is spawned as a child process by  
the MCP host — you do not run it manually in most cases.

To test it directly:

```bash
python server.py
```

Then paste a raw JSON-RPC message, e.g.:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}
```

---

## Registering with an MCP host

Add to your `mcp.json` (workspace or global):

```json
{
  "mcpServers": {
    "mnevis": {
      "command": "python",
      "args": ["/absolute/path/to/mnevis-mcp/server.py"],
      "env": {
        "MNEVIS_URL":   "http://localhost",
        "MNEVIS_PORT":  "11434",
        "MNEVIS_MODEL": "llama3",
        "MNEVIS_API_KEY": ""
      }
    }
  }
}
```

For VScode:

```json
{
  "servers": {
    "mnevis": {
      "command": "python",
      "args": ["/absolute/path/to/mnevis-mcp/server.py"],
      "env": {
        "MNEVIS_URL":   "http://localhost",
        "MNEVIS_PORT":  "11434",
        "MNEVIS_MODEL": "llama3",
        "MNEVIS_API_KEY": ""
      }
    }
  }
}
```

Replace the `args` path with the actual absolute path on your machine.  
Set `MNEVIS_PORT` / `MNEVIS_MODEL` to match your local LLM setup.

---

## Exposed tool

### `do_everything`

| Argument | Type   | Required | Description                                                      |
|----------|--------|----------|------------------------------------------------------------------|
| `prompt` | string | ✅        | The full task, question, or conversation to process              |
| `system` | string | ❌        | Optional system / persona instruction for the local LLM          |

The tool description explicitly instructs the calling agent to **send every task here** rather than reasoning itself.

### `health_check`

| Argument | Type   | Required | Description |
|----------|--------|----------|-------------|
| *(none)* | —      | —        | Returns a short status string containing the server version, configured model name, URL/port and request timeout. Useful for monitoring or debugging.

**Example request**
```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health_check","arguments":{}}}
```

**Example response**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "mnevis version 1.0.0 | model=llama3 | url=http://localhost:11434 | timeout=120s"}],
    "isError": false
  }
}
```

---

## Project layout

```
mnevis-mcp/
├── server.py        # MCP server (single file, stdlib only)
├── pyproject.toml   # Project metadata
├── README.md        # This file
└── .gitignore
```

---

## License

MIT