own-your-code 0.1.6

Own Your Code — MCP server + UI: record why each function exists, tradeoffs, and evolution (SQLite)

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

---

Documentation map

Doc	Who it’s for
This README	Install, configure, CLI, API, deploy — start here
docs/USER-GUIDE.md	Plain-language tour: pip, MCP, FastAPI, UI, mental models
AGENTS.md	For MCP / AI assistants — when to call record_intent, record_evolution, etc. (not maintainer-only)
docs/CODING-PRACTICES.md	Contributing and code conventions
templates/PROJECT-INTENT.md	Drop into repos so every session knows your expectations

---

Table of contents

1. What you get
2. Architecture (at a glance)
3. Requirements
4. Quick start in five steps
5. Install (all options)
6. MCP host configuration
7. Terminal CLI
8. Web UI and API
9. MCP tools
10. REST API
11. Search modes
12. Optional extras (semantic, multi-language)
13. Post-write hook
14. Production deployment
15. Development
16. Database schema
17. Publishing (maintainers)
18. License

---

What you get

• Intent — User request, reasoning, implementation notes, confidence (record_intent).
• Decisions — Tradeoffs and alternatives you considered.
• Evolution — Timeline of behavioral changes (record_evolution).
• Indexing — Python, TypeScript, JavaScript, Go (pluggable extractors).
• Search — Keyword, semantic (embeddings), or hybrid.
• Surfaces — MCP (agents), FastAPI + React UI (humans), CLI (scripts, CI).

New to packaging or MCP? Read docs/USER-GUIDE.md after skimming the steps below.

---

Architecture (at a glance)

flowchart LR
  subgraph agents["AI / MCP"]
    Host[Cursor, Claude, …]
  end
  subgraph oyc["Own Your Code"]
    MCP[own-your-code-mcp]
    API[FastAPI api.main]
    UI[React UI]
  end
  DB[(SQLite)]
  Host --> MCP
  MCP --> DB
  UI --> API
  API --> DB

• MCP and REST share the same database (path from OWN_YOUR_CODE_DB or default owns.db in the server working directory).

---

Requirements

• Python 3.11+ (3.11, 3.12, 3.13 supported in CI).
• Node.js only if you build or develop the UI (ui/).

---

Quick start in five steps

Step	Action
1	Install the package (pipx / pip / source) so own-your-code-mcp is on your PATH.
2	Run own-your-code install (or merge JSON manually) — see MCP host configuration.
3	Restart your editor and call register_project with the absolute path to your repo.
4	While coding, use record_intent (and record_evolution when behavior changes). See AGENTS.md.
5	Optional: run the Web UI to browse coverage, search, and timelines.

---

Install (all options)

PyPI (recommended for end users)

pipx install own-your-code
own-your-code install

Or with pip:

python3 -m pip install own-your-code
own-your-code install --platform editor-a

install merges the MCP server block into known config files. Platform IDs:

ID	Typical host
editor-a	Cursor (~/.cursor/mcp.json)
editor-b	Claude Desktop
editor-c	Windsurf / Codeium
all	Every location above

Repeat --platform or use all. Inspect what would change: own-your-code install --dry-run.

npm wrapper (still needs Python 3.11+)

npx own-your-code-mcp install

This ensures the Python package is installed, then runs the same own-your-code install. Prefer own-your-code-mcp on PATH for day-to-day MCP (lower latency than a Node shim).

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   # Windows: .venv\Scripts\activate
pip install -e .

# Optional capability bundles:
pip install -e ".[semantic]"   # embeddings + semantic/hybrid search
pip install -e ".[full]"       # semantic + tree-sitter TS/JS/Go
pip install -e ".[dev,full]"  # + pytest, ruff (contributors)

Manual MCP JSON (skip install)

own-your-code print-config

If own-your-code-mcp is missing but uvx exists, install may write uvx --from own-your-code own-your-code-mcp (package must exist on PyPI).

---

MCP host configuration

After own-your-code install, restart the editor.

The repo includes mcp.example.json as a minimal mcpServers fragment you can copy or diff against own-your-code print-config.

From a git checkout (example — adjust paths):

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

When installed as a package:

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

Then in your MCP client, register and record intent (examples are illustrative; use your host’s tool UI):

register_project path="/absolute/path/to/your/project"

record_intent
  project_path="/absolute/path/to/your/project"
  file="src/auth.py"
  function_name="verify_token"
  user_request="Add JWT verification so the API rejects unsigned requests"
  reasoning="PyJWT + RS256; asymmetric keys for verify-only services."

---

Terminal CLI

Same SQLite database as MCP. No editor required.

Command	Purpose
own-your-code --help	All subcommands
own-your-code install	Merge MCP config into host JSON files
own-your-code print-config	Print mcpServers fragment
own-your-code status [--project-path P]	DB path; if cwd is inside a registered project, show its stats, else list projects (or use --project-path)
own-your-code update [PATH]	Scan/index a project (like register_project); PATH defaults to the current directory
own-your-code prune [PATH] [--dry-run]	Remove stale functions rows (and linked intents, etc.) not in a fresh scan; fixes inflated counts after narrowing skip rules
own-your-code visualize [--project-path P] --out report.html	Standalone HTML report; P defaults to cwd (must lie inside a registered root)
own-your-code watch [--project-path P]	Print coverage stats on an interval; P defaults to cwd

Use OWN_YOUR_CODE_DB to point at a specific database file.

---

Web UI and API

Run the server

From the repository root (where api/ and pyproject.toml live):

pip install -e . # or ensure fastapi + uvicorn are available
cd ui && npm ci && npm run build && cd ..   # first time: build static UI
uvicorn api.main:app --reload --host 127.0.0.1 --port 8002

Open http://127.0.0.1:8002 — FastAPI serves ui/dist when present.

Vite dev (hot reload UI, API still on 8002):

# terminal 1
uvicorn api.main:app --reload --port 8002
# terminal 2
cd ui && npm install && npm run dev

Dev server: http://localhost:5175 (proxies API routes to 8002).

If the API runs on another host or port, set VITE_API_PROXY (for example in ui/.env.development: VITE_API_PROXY=http://127.0.0.1:8003) so Vite proxies /evolution, /projects, and other API paths to the correct server. Without this, Timeline and other tabs can show a JSON parse error when the proxy hits the wrong process and returns HTML.

Using the UI

1. In the header, enter the absolute path to your project and click Register (or pick a saved project).
2. Explore Intent Map, Features, Search, Timeline; open Swagger / ReDoc from the footer.
3. If OWN_YOUR_CODE_API_KEY is set on the server, use API key… in the footer so the browser sends X-Api-Key on data requests. /health and /server-info stay public.

API docs

• Swagger: http://127.0.0.1:8002/docs
• ReDoc: http://127.0.0.1:8002/redoc
• Server metadata: GET /server-info (version, semantic deps, whether auth is enabled)

---

MCP tools

Tool	Description
register_project	Scan and index a codebase
record_intent	Record why a function exists
record_evolution	Log a behavioral change
explain_function	Intent, decisions, evolution for one function
find_by_intent	Keyword / semantic / hybrid search
embed_intents	Backfill embeddings for semantic search
get_codebase_map	Map, coverage, hook backlog
get_evolution	Evolution entries for one function
annotate_existing	Retrofit intents on legacy code
mark_file_reviewed	Clear hook backlog without new intent

---

REST API

Method	Path	Description
GET	/health	Health (public)
GET	/server-info	Version & capability flags (public)
GET	/projects	List projects
POST	/register	Register + index
GET	/map	Codebase map (?file= optional)
GET	/function	One function’s intent stack
POST	/search	Keyword / semantic / hybrid
POST	/embed	Start embed job
GET	/embed/{job_id}	Job status
GET	/stats	Coverage + backlog
GET	/features	Features
GET	/evolution	Project evolution timeline
GET	/graph	Graph payload for ReactFlow-style UIs

Example:

curl -s -X POST http://127.0.0.1:8002/search \
  -H "Content-Type: application/json" \
  -d '{"project_path":"/path/to/repo","query":"payments","mode":"hybrid"}'

---

Search modes

Mode	When to use
keyword	Fast substring search over intent text
semantic	Natural-language similarity (run embed_intents / UI “Index embeddings” first)
hybrid	Blend keyword ranking + semantic score (semantic_weight tunable)

---

Optional extras (semantic, multi-language)

Extra	Install	Enables
semantic	pip install "own-your-code[semantic]"	sentence-transformers, numpy, vector search
multilang	pip install "own-your-code[multilang]"	tree-sitter parsers for TS/JS/Go
full	pip install "own-your-code[full]"	Both of the above
dev	pip install "own-your-code[dev]"	pytest, httpx, ruff

Register with filters (REST body or MCP args as supported):

{
  "path": "/my/project",
  "languages": ["python", "typescript"],
  "include_globs": ["src/**/*.ts", "src/**/*.py"],
  "ignore_dirs": ["vendor", "generated"]
}

Default skips: Indexing always skips common tooling and dependency trees (for example node_modules, .git, .venv, .venv-pypi-test, .pytest_cache, .ruff_cache, site-packages, dist, build, htmlcov, Pods, and paths under *.egg-info). Use ignore_dirs to add project-specific folder names.

Language	Parser	Notes
Python	ast	Always available
TypeScript / JavaScript	tree-sitter (optional)	Regex fallback without extra
Go	tree-sitter (optional)	Regex fallback without extra

---

Post-write hook

Tracks edited files so get_codebase_map can show a hook backlog until you record_intent or mark_file_reviewed.

cp hooks/post_write.py .git/hooks/post-write && chmod +x .git/hooks/post-write
# or, if installed:
own-your-code-hook

Wire the hook to your editor’s “after save” hook path as needed.

---

Production deployment

Environment variables

Variable	Default	Meaning
OWN_YOUR_CODE_DB	owns.db	SQLite path
OWN_YOUR_CODE_API_KEY	(unset)	Require X-Api-Key on data routes; SPA shell + /assets + /health + /server-info stay public
OWN_YOUR_CODE_CORS_ORIGINS	*	Comma-separated origins
OWN_YOUR_CODE_EMBED_MODEL	all-MiniLM-L6-v2	Embedding model name

Docker

docker compose up

Or:

docker build -t own-your-code .
docker run -p 8002:8002 \
  -e OWN_YOUR_CODE_API_KEY=your-secret \
  -e OWN_YOUR_CODE_CORS_ORIGINS=https://yourapp.com \
  -v "$(pwd)/data:/data" \
  -e OWN_YOUR_CODE_DB=/data/owns.db \
  own-your-code

Render / Fly.io

A render.yaml is included. Set OWN_YOUR_CODE_API_KEY and OWN_YOUR_CODE_DB in the provider dashboard.

---

Development

See docs/CODING-PRACTICES.md.

pip install -e ".[dev,full]"
pytest
ruff check src/ api/ tests/
cd ui && npm ci && npm run build

CI runs on Python 3.11, 3.12, and 3.13.

---

Database schema

SQLite tables (version via PRAGMA user_version; migrations are additive-safe):

Table	Role
projects	Registered roots
functions	Extracted functions
intents	Why a function exists
intent_embeddings	Vectors for semantic search
decisions	Tradeoffs
evolution	Change history
features / feature_links	Feature grouping
hook_events	Post-write backlog

---

Publishing (maintainers)

1. PyPI — Project own-your-code on pypi.org; trusted publisher for this repo + .github/workflows/release.yml (docs).
2. npm — npm login or GitHub secret NPM_TOKEN for npm/own-your-code-mcp.

Release: bump version in pyproject.toml and npm/own-your-code-mcp/package.json, then tag:

git tag v0.1.0
git push origin main && git push origin v0.1.0

Manual PyPI / npm: use python -m build + twine upload, and npm publish from npm/own-your-code-mcp.

---

License

MIT