# linkml-mcp

MCP server for commit-addressed editing of LinkML YAML schemas.

See [SCOPE.md](SCOPE.md) for the project scope and milestone boundaries.

## Setup

```bash
uv sync --dev
```

## Run The MCP Server

For local editor/Codex testing, HTTP is currently the recommended transport:

```bash
uv run linkml-mcp --transport http --host 127.0.0.1 --port 8765
```

To accept requests through a hostname or reverse proxy, bind beyond localhost and allow the external Host header:

```bash
uv run linkml-mcp \
  --transport http \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host essentialcomplexity.eu
```

If the proxy forwards a different Host header, pass that value with another `--allowed-host`.

Use this MCP config:

```json
{
  "servers": {
    "linkml-server": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  },
  "inputs": []
}
```

Stdio is also available:

```bash
uv run linkml-mcp
```

The server stores workspaces under `.linkml-mcp/workspaces` by default. Override this with:

```bash
export LINKML_MCP_WORKSPACE_ROOT=/path/to/workspaces
export LINKML_MCP_GENERATOR_OUTPUT_ROOT=/path/to/generated
```

## Test Client

Create a workspace:

```bash
uv run linkml-mcp-client init --name test_schema
```

Apply a semantic changeset:

```bash
uv run linkml-mcp-client apply-change \
  --workspace-id ws_... \
  --base-commit abc123 \
  --changes-json examples/add_person.json \
  --message "Add Person"
```

Read a schema at a commit:

```bash
uv run linkml-mcp-client read-schema \
  --workspace-id ws_... \
  --commit-id def456
```

Run tests:

```bash
uv run pytest
```