okf-mcp

An MCP server that gives LLMs full read/write access to an Open Knowledge Format (OKF) v0.1 knowledge bundle — usable as structured, persistent long-term memory.

Built with FastMCP and UV.

---

What is OKF?

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

---
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

Install

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

Run (stdio — for MCP clients)

uv run okf-mcp

Run (HTTP — for testing)

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:

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:

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:

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:

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

---

VS Code Integration

Local UV server with GitHub Copilot

1. Install VS Code and the Python extension.
2. Install UV.
3. Install and sign in to the 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:

{
  "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:

"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:

"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