mcp-own-your-code

Own Your Code

A living intent ledger for your codebase.
_{Capture the why behind every function — via MCP — and explore it in a browser or over REST.}

Own Your Code is an open-source Model Context Protocol (MCP) server and optional FastAPI + React web app that maintains an intent ledger (SQLite). For each function in your codebase, it captures why it exists, what tradeoffs were considered, and how it has evolved over time — making your codebase understandable to both humans and AI.

Works with: Cursor, Claude Desktop, Claude Code, Windsurf, VS Code (with MCP), and any other MCP-capable host.

Package name: own-your-code on PyPI. Repository: mcp-own-your-code.

---

Where to find Own Your Code

Where	Link
PyPI	pypi.org/project/own-your-code
GitHub	github.com/khirodsahoo93/mcp-own-your-code
npm shim	npmjs.com/package/own-your-code-mcp

---

Table of contents

1. Why Own Your Code?
2. What you get
3. Architecture
4. Requirements
5. Quick start (5 steps)
6. Installation
7. Editor setup (per-editor)
8. Your first session
9. MCP tools reference
10. Terminal CLI reference
11. Web UI and REST API
12. REST API reference
13. Search modes
14. Optional extras
15. Environment variables
16. Post-write hook
17. Long-running tools and limits
18. Production deployment
19. Development
20. Database schema
21. Troubleshooting
22. Publishing (maintainers)
23. Documentation map
24. License

---

Why Own Your Code?

Code explains what — your history of decisions explains why. When you return to a function six months later (or when an AI tries to help you change it), the context is gone. Reviewers ask "why is this here?" Pull requests lose the reasoning thread.

Own Your Code solves this by making intent capture a first-class part of your workflow:

• Every time you write or modify a function, record why it exists and what decision you made.
• When you return to it later, explain_function surfaces the full story — original request, decisions, every change with its reason.
• The codebase map shows coverage (what % of functions have intent recorded) and highlights what still needs annotation.
• Semantic search lets you find functions by purpose, not just name.

---

What you get

Feature	Description
Intent capture	Record user request, reasoning, implementation notes, confidence level per function.
Decision log	Capture tradeoffs and alternatives considered at decision time.
Evolution timeline	Append a change entry whenever behavior is modified; Git hash is captured automatically.
Multi-language indexing	Python (built-in), TypeScript, JavaScript, Go (via optional tree-sitter).
Three search modes	Keyword (fast), semantic (embedding-based), hybrid (blended).
Coverage map	See which functions are annotated and which still need attention.
MCP surface	AI agents call tools directly from the editor.
CLI surface	Same database, same project — use from the terminal without an AI host.
FastAPI + React UI	Browse the map, search, inspect timelines in a browser.
Post-write hook	Editor hook populates a backlog of files to annotate after each write.

---

Architecture

flowchart LR
  subgraph ai["AI Host (editor)"]
    Cursor["Cursor / Claude / Windsurf"]
  end
  subgraph mcp["MCP Process"]
    Srv["own-your-code-mcp (stdio)"]
  end
  subgraph web["Optional web stack"]
    API["FastAPI api.main"]
    UI["React UI (ui/dist)"]
  end
  DB[(SQLite ledger<br/>owns.db)]

  Cursor -->|"JSON-RPC over stdio"| Srv
  Srv --> DB
  Browser --> API
  API --> DB
  API --> UI

Key points:

• The MCP server and the REST API share one SQLite file (path from OWN_YOUR_CODE_DB, or a default location).
• One MCP binary serves all your projects. The active project is always identified by project_path on each tool call.
• The web stack (FastAPI + React) is optional — MCP works without it.

---

Requirements

• Python 3.11, 3.12, or 3.13 — all tested in CI.
• Node.js 18+ — only needed if you build the React UI from source.
• No database server — SQLite is embedded.

---

Quick start (5 steps)

Step	What to do
1	Install: pipx install own-your-code
2	Wire your editor: own-your-code install (or see per-editor setup)
3	Restart your editor so it picks up the new MCP config
4	In the AI chat, call register_project with the path to your repo
5	While coding, call record_intent after every function you write or change

---

Installation

Option A — pipx (recommended for most users)

pipx installs CLI tools in isolation and puts them on your PATH automatically.

pipx install own-your-code
own-your-code install          # writes MCP config for your editor

First time: follow the prompt if pipx asks you to add ~/.local/bin to PATH.

Option B — pip in a virtual environment

python3 -m venv ~/.venvs/oyc
source ~/.venvs/oyc/bin/activate    # Windows: .venvs\oyc\Scripts\activate
pip install own-your-code
own-your-code install

When you configure your editor, use the full path to the binary:

which own-your-code-mcp    # copy this path into the MCP config command

Option C — npm shim (still requires Python 3.11+)

npx own-your-code-mcp install

This checks for the Python package, installs it if needed, then runs own-your-code install. Prefer the native Python binary for lower latency.

Option D — from source

git clone https://github.com/khirodsahoo93/mcp-own-your-code
cd mcp-own-your-code
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Optional extras:
pip install -e ".[semantic]"       # semantic/hybrid search
pip install -e ".[full]"           # semantic + TypeScript/JavaScript/Go indexing
pip install -e ".[dev,full]"       # full + pytest + ruff

Optional extras

Extra	What it adds
pip install "own-your-code[semantic]"	sentence-transformers, numpy — needed for semantic/hybrid search
pip install "own-your-code[multilang]"	tree-sitter grammars for TypeScript, JavaScript, Go
pip install "own-your-code[full]"	Both semantic and multilang
pip install "own-your-code[dev]"	pytest, httpx, ruff — for contributors

---

Editor setup (per-editor)

After installing, run own-your-code install --platform <id> to write the MCP config automatically. Or use own-your-code print-config to get the JSON and merge it manually.

Always restart the editor after changing MCP config.

Cursor

own-your-code install --platform editor-a

Edits ~/.cursor/mcp.json. Manual config:

{
  "mcpServers": {
    "own-your-code": {
      "command": "own-your-code-mcp",
      "args": [],
      "env": {}
    }
  }
}

If own-your-code-mcp is not on PATH (pip in venv, no pipx), use the full path instead:

{
  "mcpServers": {
    "own-your-code": {
      "command": "/Users/you/.venvs/oyc/bin/own-your-code-mcp",
      "args": [],
      "env": {}
    }
  }
}

Claude Desktop

own-your-code install --platform editor-b

Edits ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Windsurf / Codeium

own-your-code install --platform editor-c

Edits ~/.codeium/windsurf/mcp_config.json.

Claude Code CLI

own-your-code install --platform claude-code

Edits ~/.claude.json.

VS Code with MCP extension

Use own-your-code print-config to get the server block and add it to your MCP configuration file per your extension's docs.

All editors at once

own-your-code install --platform all

Check without writing

own-your-code install --dry-run

From a git checkout (not a pip/pipx install)

{
  "mcpServers": {
    "own-your-code": {
      "command": "/path/to/mcp-own-your-code/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-own-your-code"
    }
  }
}

---

Your first session

This section shows a realistic workflow: registering a project, recording intent while writing code, and retrieving it later.

1. Register your project

In the AI chat:

register_project path="/Users/you/projects/my-app"

This walks the directory tree, extracts every function in Python/Ty

---

README truncated. View full README on GitHub.