EyeTools MCP Framework

EyeTools is a Python MCP server that dynamically discovers tools from their configuration and exposes them over MCP and HTTP. This distribution contains the server and its core infrastructure; it ships with no domain tool packages, model weights, or datasets.

Read the documentation in English or 中文.

Requirements and installation

Python 3.12 or later and uv are required. From the project root:

uv sync
uv run eyetools-mcp serve --host 127.0.0.1 --port 8000 --tools-dir tools

The empty server reports {"status":"ok","tools":0} at http://127.0.0.1:8000/health. HTTP API documentation is available at /docs; the MCP streamable HTTP endpoint is /mcp. The API has no built-in authentication; restrict access with an authenticated proxy if exposing it remotely.

The project includes the existing Apache 2.0 license. It does not install PyTorch or other model libraries in the server environment. Install tool-specific packages in their tool environment as described below.

Related MCP server: Magg

Adding a tool

Place a directory containing config.yaml in a scanned tool root. The entry is module:Class, relative to the tool directory. Each class receives (meta, params) and implements predict(request); the server passes the tool input in request["inputs"]. Return a JSON-serializable value. Optional hooks include prepare, load_model, warmup, and shutdown. When subclassing ToolBase, call super().load_model() after loading a model so the framework tracks its loaded state.

The following minimal example can be created locally to test the interface; no tool packages are included in this distribution.

tools/
└── echo/
    ├── config.yaml
    └── echo_impl.py

tools/echo/config.yaml:

id: echo
package: echo
entry: echo_impl:EchoTool
runtime:
  load_mode: inproc
  device_policy: cpu_only
model:
  device: cpu
io:
  description: Return the supplied message.
  input_schema:
    type: object
    properties:
      message:
        type: string
    required: [message]

tools/echo/echo_impl.py:

class EchoTool:
    def __init__(self, meta, params):
        self.meta = meta
        self.params = params

    def predict(self, request):
        return {"message": request["inputs"]["message"]}

Start or restart the server after adding the files. Check discovery and invoke the tool through HTTP:

curl http://127.0.0.1:8000/tools
curl -X POST http://127.0.0.1:8000/predict \
  -H 'Content-Type: application/json' \
  -d '{"tool_id":"echo","request":{"inputs":{"message":"hello"}}}'

The response contains "output":{"message":"hello"}. MCP clients can list and call the echo tool through http://127.0.0.1:8000/mcp. The io.input_schema describes the exposed MCP arguments. The configuration also supports multiple variants and tools per package; see eyetools/core/config_loader.py for the supported fields.

Subprocesses and tool environments

Set runtime.load_mode: subprocess to run a tool in a worker process. Tools can select their own envs/<name>/pyproject.toml with environment_ref: <name>. For a tool in this checkout, create its environment and install the framework and tool-specific dependencies:

mkdir -p envs/my-tool
cd envs/my-tool
uv init --no-package --no-workspace --python 3.12
uv add --no-workspace --editable ../..
uv add --no-workspace <tool-dependency>
cd ../..

Set environment_ref: my-tool in the tool configuration. Use a Python version compatible with both the tool and the framework. Worker execution uses uv; the server working directory is the workspace root used to resolve envs/ and relative paths.

Tools requiring GPU allocation can declare the relevant runtime policy and model.weight_paths. uv run eyetools-mcp estimate-vram --tool-path tools estimates memory using declared files. No tool-specific weight paths or profiles are bundled.

Server architecture

• eyetools/core/config_loader.py, schema.py, loader.py, and registry.py: configuration normalization, discovery, and metadata.

• tool_manager.py, process_manager.py, and worker_entry.py: execution, lifecycle, worker IPC, and resource management.

• env_manager.py, gpu_allocator.py, and vram_estimator.py: isolated environments and optional device allocation.

• eyetools/mcp_server.py and eyetools/cli.py: MCP/HTTP API and CLI.

Use --lifecycle-mode lazy to load on first use, eager to preload, or dynamic for idle eviction. Management endpoints include /lifecycle, /metrics, /admin/resources, /admin/preload/{tool_id}, and /admin/evict.

Development

uv run pytest
uv build

The integration tests generate temporary, non-domain tools and exercise discovery, in-process and subprocess execution, and MCP calls. No tool or model is needed to run the tests.