# modular-mcp

Modular MCP server with Odoo-style addons (`__manifest__.toml`) plus an optional FastAPI web layer.

## Setup

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
copy .env.example .env
```

Configuration is primarily in [`config.toml`](config.toml). Environment variables still override FastAPI settings (`.env` supported).

| Source | Purpose |
|--------|---------|
| `config.toml` (default) | MCP server, logging, addon paths, FastAPI defaults |
| `--config` / `-c` | Alternate profile (path relative to CWD; see below) |
| `MODULAR_MCP_CONFIG` | Same as `--config` when flag omitted |
| `.env` / env vars | Override FastAPI `HOST`, `PORT`, `LOG_LEVEL`, etc. |

**Relative paths** inside a config file (`addons_paths`, `log_dir`, `data_file`) resolve from the **directory of that config file**, not from the package install root.

Tool-specific settings (timeout, retries, …) belong in each addon's `config.toml`, not the host profile. Host `[logging.addons.<log_key>]` only overrides addon logging when needed.

## Run

```bash
modular-mcp serve
modular-mcp mcp serve
modular-mcp get hello

# External profile (separate config + addon paths)
modular-mcp --config /path/to/profile/config.toml mcp serve
```

- FastAPI UI: `http://127.0.0.1:8000/`
- MCP default: `streamable-http` on `http://127.0.0.1:5001` (see `config.toml`)

## Addons

Each addon is a folder under `addons/` with:

```text
addons/my_addon/
  __manifest__.toml
  config.toml
  tools.py          # register_tools(mcp, config, logger)
```

Sample addon: [`addons/key_value_store/`](addons/key_value_store/) with `kv_get` / `kv_set`.

Shared imports inside addons:

```python
from app.mcp.utils import format_json, exception_to_error_response
from app.mcp.logging import monitor_performance
from helpers import my_helper  # local module in the same addon folder
```

### Port external tools into an addon

```text
# Before (standalone tool module)
tools/my_tool.py

# After
addons/my_tool/
  __manifest__.toml
  config.toml
  tools.py
```

Move the tool code into `tools.py`, change shared imports to `app.mcp.utils` / `app.mcp.logging`, and set `log_key` in `__manifest__.toml`.

## Test & lint

```bash
pytest
ruff check .
ruff format --check .
mypy
pyright
```

## Pre-commit

```bash
pip install -e ".[dev]"
pre-commit install
pre-commit run --all-files
```