# okf-mcp

An [MCP](https://modelcontextprotocol.io) server that gives LLMs full read/write
access to an [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
knowledge bundle — usable as structured, persistent long-term memory.

Built with [FastMCP](https://gofastmcp.com) and [UV](https://docs.astral.sh/uv/).

---

## What is OKF?

OKF represents knowledge as a directory of plain markdown files with YAML
frontmatter. Every file is a *concept*:

```markdown
---
type: Memory          # REQUIRED — what kind of thing this is
title: Project kickoff notes
description: Key decisions from the 2026-07-12 kickoff meeting
tags: [project-alpha, decisions]
timestamp: 2026-07-12T09:00:00Z
---

# Decisions

- Use OKF as the canonical knowledge format.
- Bundle stored in git alongside the codebase.
```

Concepts are organised in a directory hierarchy and can cross-link to each other
with standard markdown links. Two reserved filenames have special meaning:
`index.md` (directory listing) and `log.md` (change history).

---

## MCP Tools

| Tool | Description |
|---|---|
| `list_concepts` | List all concepts (or a subdirectory) |
| `get_concept` | Read a full concept by ID |
| `search_concepts` | Full-text + tag + type search |
| `get_index` | Read an `index.md` file |
| `get_log` | Read a `log.md` file |
| `create_concept` | Create a new concept (fails if exists) |
| `update_concept` | Update body and/or frontmatter fields |
| `delete_concept` | Delete a concept |
| `update_index` | Write a custom `index.md` |
| `generate_index` | Auto-generate `index.md` from frontmatter |
| `append_log_entry` | Append a dated entry to `log.md` |

---

## Quick Start

### Requirements

- Python 3.11+
- [UV](https://docs.astral.sh/uv/getting-started/installation/)

### Install

```bash
git clone <this-repo>
cd okf-mcp
uv sync
```

### Run (stdio — for MCP clients)

```bash
uv run okf-mcp
```

### Run (HTTP — for testing)

```bash
uv run fastmcp run src/okf_mcp/server.py:mcp --transport http --port 8000
```

### Run with Docker

The Docker image serves MCP over HTTP on port `8000`. Mount the bundle so
memories persist when the container is recreated:

```bash
docker build -t okf-mcp .
docker run --rm -p 8000:8000 \
  -v okf-bundle:/app/bundle \
  okf-mcp
```

The MCP endpoint is `http://localhost:8000/mcp`. To use this repository's local
bundle instead of a named Docker volume, run:

```bash
docker run --rm \
  --name okf-mcp \
  --user "$(id -u):$(id -g)" \
  -p 8000:8000 \
  --mount type=bind,src=/home/matteo/Documents/Dev/Personal/okf-mcp/bundle,dst=/app/bundle,rw \
  okf-mcp
```

The `--user` option prevents Docker from creating root-owned files in the
mounted bundle. To run the container in the background:

```bash
docker run -d \
  --name okf-mcp \
  --restart unless-stopped \
  --user "$(id -u):$(id -g)" \
  -p 8000:8000 \
  --mount type=bind,src=/home/matteo/Documents/Dev/Personal/okf-mcp/bundle,dst=/app/bundle,rw \
  okf-mcp
```

Use `docker logs -f okf-mcp` to view logs and `docker stop okf-mcp` to stop it.

### Configure the bundle path

By default the bundle lives at `./bundle` (relative to the working directory).
Override it with the `OKF_BUNDLE_PATH` environment variable:

```bash
OKF_BUNDLE_PATH=/path/to/my/bundle uv run okf-mcp
```

---

## VS Code Integration

### Local UV server with GitHub Copilot

1. Install [VS Code](https://code.visualstudio.com/) and the
   [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python).
2. Install [UV](https://docs.astral.sh/uv/getting-started/installation/).
3. Install and sign in to the
   [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extensions.
4. Open this repository as a folder in VS Code.
5. Run `uv sync` once in the integrated terminal.
6. Open the Command Palette with `Ctrl+Shift+P`, run **MCP: List Servers**,
   select `okf-knowledge-server`, and choose **Start** if necessary.
7. Open Copilot Chat, switch to **Agent** mode, and allow the server tools when
   prompted.

The repository includes `.vscode/mcp.json`. It starts the local server with UV
and uses `${workspaceFolder}/bundle` as the memory store, so no manual MCP
configuration is required in VS Code.

### Docker server with GitHub Copilot

If the Docker container is running on port `8000`, change `.vscode/mcp.json` to
use the HTTP endpoint instead of the local stdio server:

```json
{
  "servers": {
    "okf-knowledge-server": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

Restart the MCP server from the Command Palette after saving the file. Use
either the UV configuration or the Docker configuration, not both at the same
time.

### Cline

Cline uses its own MCP settings file. For the local UV server, configure
`okf-knowledge-server` with the project path and bundle path:

```json
"okf-knowledge-server": {
  "type": "stdio",
  "command": "uv",
  "args": [
    "run",
    "--project",
    "/home/matteo/Documents/Dev/Personal/okf-mcp",
    "okf-mcp"
  ],
  "env": {
    "OKF_BUNDLE_PATH": "/home/matteo/Documents/Dev/Personal/okf-mcp/bundle"
  },
  "disabled": false,
  "autoApprove": []
}
```

For the Docker server, use an HTTP entry instead:

```json
"okf-knowledge-server": {
  "type": "streamableHttp",
  "url": "http://127.0.0.1:8000/mcp",
  "disabled": false,
  "autoApprove": []
}
```

After changing Cline's settings, restart or reconnect the MCP server in the
Cline MCP panel. Ask Cline to list the available tools; it should show
`get_concept`, `create_concept`, `search_concepts`, and the other OKF tools.

---

## Security

- All file paths are validated against `BUNDLE_ROOT` to prevent path traversal.
- Reserved filenames (`index.md`, `log.md`) are protected from concept
  create/update/delete operations.

---

## Project Layout

```
src/okf_mcp/
├── __init__.py   — exports `mcp`
└── server.py     — FastMCP server with all tools

bundle/           — Default OKF knowledge bundle (git-tracked)
└── index.md      — Bundle root index
```