own-your-code 0.1.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- api/__init__.py +1 -0
- api/main.py +277 -0
- own_your_code-0.1.3.dist-info/METADATA +396 -0
- own_your_code-0.1.3.dist-info/RECORD +19 -0
- own_your_code-0.1.3.dist-info/WHEEL +4 -0
- own_your_code-0.1.3.dist-info/entry_points.txt +4 -0
- own_your_code-0.1.3.dist-info/licenses/LICENSE +21 -0
- src/__init__.py +1 -0
- src/cli.py +183 -0
- src/db.py +571 -0
- src/embeddings.py +212 -0
- src/extractor.py +185 -0
- src/extractors/__init__.py +40 -0
- src/extractors/base.py +46 -0
- src/extractors/go_extractor.py +158 -0
- src/extractors/python_extractor.py +20 -0
- src/extractors/typescript_extractor.py +183 -0
- src/post_write_hook.py +77 -0
- src/server.py +702 -0
api/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# FastAPI app package (see main.py).
|
api/main.py
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
"""
|
|
2
|
+
FastAPI backend for the Own Your Code UI.
|
|
3
|
+
|
|
4
|
+
Local: ``uvicorn api.main:app --reload --port 8002``
|
|
5
|
+
|
|
6
|
+
Production: set ``PORT`` (e.g. Render/Fly). Optional ``OWN_YOUR_CODE_DB`` for SQLite path.
|
|
7
|
+
|
|
8
|
+
Auth:
|
|
9
|
+
Set ``OWN_YOUR_CODE_API_KEY`` to require ``X-Api-Key: <key>`` on every request.
|
|
10
|
+
Leave unset to run without auth (local / trusted-network only).
|
|
11
|
+
|
|
12
|
+
CORS:
|
|
13
|
+
Set ``OWN_YOUR_CODE_CORS_ORIGINS`` to a comma-separated list of allowed origins
|
|
14
|
+
(e.g. ``https://myapp.example.com,https://admin.example.com``).
|
|
15
|
+
Defaults to ``*`` (open) when unset.
|
|
16
|
+
"""
|
|
17
|
+
import os
|
|
18
|
+
import sys
|
|
19
|
+
import uuid
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
from typing import Optional
|
|
22
|
+
|
|
23
|
+
from fastapi import BackgroundTasks, Depends, FastAPI, Header, HTTPException
|
|
24
|
+
from fastapi.middleware.cors import CORSMiddleware
|
|
25
|
+
from fastapi.staticfiles import StaticFiles
|
|
26
|
+
from fastapi.responses import FileResponse
|
|
27
|
+
from pydantic import BaseModel
|
|
28
|
+
|
|
29
|
+
sys.path.insert(0, str(Path(__file__).parent.parent))
|
|
30
|
+
from src import db
|
|
31
|
+
from src import embeddings as emb
|
|
32
|
+
from src.extractor import scan_project_multi
|
|
33
|
+
|
|
34
|
+
# ── config from environment ────────────────────────────────────────────────
|
|
35
|
+
|
|
36
|
+
_API_KEY = os.environ.get("OWN_YOUR_CODE_API_KEY", "").strip()
|
|
37
|
+
_CORS_RAW = os.environ.get("OWN_YOUR_CODE_CORS_ORIGINS", "*")
|
|
38
|
+
_CORS_ORIGINS = [o.strip() for o in _CORS_RAW.split(",") if o.strip()]
|
|
39
|
+
|
|
40
|
+
# ── auth ───────────────────────────────────────────────────────────────────
|
|
41
|
+
|
|
42
|
+
def _auth(x_api_key: Optional[str] = Header(None, alias="X-Api-Key")):
|
|
43
|
+
"""Require X-Api-Key header when OWN_YOUR_CODE_API_KEY is set."""
|
|
44
|
+
if _API_KEY and x_api_key != _API_KEY:
|
|
45
|
+
raise HTTPException(401, "Invalid or missing API key. Set X-Api-Key header.")
|
|
46
|
+
|
|
47
|
+
# ── app ────────────────────────────────────────────────────────────────────
|
|
48
|
+
|
|
49
|
+
app = FastAPI(
|
|
50
|
+
title="Own Your Code",
|
|
51
|
+
description="Living intent map — why your code exists, captured as you build via MCP.",
|
|
52
|
+
dependencies=[Depends(_auth)],
|
|
53
|
+
)
|
|
54
|
+
app.add_middleware(
|
|
55
|
+
CORSMiddleware,
|
|
56
|
+
allow_origins=_CORS_ORIGINS,
|
|
57
|
+
allow_methods=["*"],
|
|
58
|
+
allow_headers=["*"],
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
# ── background embed job tracking ─────────────────────────────────────────
|
|
62
|
+
|
|
63
|
+
_embed_jobs: dict[str, dict] = {} # job_id -> {status, ...}
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@app.get("/health")
|
|
67
|
+
def health():
|
|
68
|
+
return {"status": "ok", "service": "own-your-code"}
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class RegisterReq(BaseModel):
|
|
72
|
+
path: str
|
|
73
|
+
name: str = ""
|
|
74
|
+
languages: list[str] = []
|
|
75
|
+
include_globs: list[str] = []
|
|
76
|
+
ignore_dirs: list[str] = []
|
|
77
|
+
|
|
78
|
+
class SearchReq(BaseModel):
|
|
79
|
+
project_path: str
|
|
80
|
+
query: str
|
|
81
|
+
mode: str = "keyword" # keyword | semantic | hybrid
|
|
82
|
+
limit: int = 20
|
|
83
|
+
semantic_weight: float = 0.5
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
@app.get("/projects")
|
|
87
|
+
def list_projects():
|
|
88
|
+
return {"projects": db.list_projects()}
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
@app.post("/register")
|
|
92
|
+
def register(req: RegisterReq):
|
|
93
|
+
if not Path(req.path).exists():
|
|
94
|
+
raise HTTPException(400, f"Path not found: {req.path}")
|
|
95
|
+
pid = db.upsert_project(req.path, req.name or None)
|
|
96
|
+
functions, errors = scan_project_multi(
|
|
97
|
+
req.path,
|
|
98
|
+
include_globs=req.include_globs or None,
|
|
99
|
+
ignore_dirs=req.ignore_dirs or None,
|
|
100
|
+
languages=req.languages or None,
|
|
101
|
+
)
|
|
102
|
+
new = 0
|
|
103
|
+
lang_counts: dict[str, int] = {}
|
|
104
|
+
for fn in functions:
|
|
105
|
+
_, is_new = db.upsert_function(pid, fn)
|
|
106
|
+
if is_new:
|
|
107
|
+
new += 1
|
|
108
|
+
lang = fn.get("language", "python")
|
|
109
|
+
lang_counts[lang] = lang_counts.get(lang, 0) + 1
|
|
110
|
+
return {"project_id": pid, "path": req.path, "functions": len(functions),
|
|
111
|
+
"new": new, "by_language": lang_counts, "errors": errors}
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@app.get("/map")
|
|
115
|
+
def codebase_map(project_path: str, file: Optional[str] = None):
|
|
116
|
+
proj = db.get_project(project_path)
|
|
117
|
+
if not proj: raise HTTPException(404, "Project not registered")
|
|
118
|
+
cmap = db.get_codebase_map(proj["id"])
|
|
119
|
+
if file:
|
|
120
|
+
if file not in cmap["by_file"]:
|
|
121
|
+
raise HTTPException(404, f"File '{file}' not in project map")
|
|
122
|
+
cmap["by_file"] = {file: cmap["by_file"][file]}
|
|
123
|
+
return cmap
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
@app.get("/features")
|
|
127
|
+
def features(project_path: str):
|
|
128
|
+
proj = db.get_project(project_path)
|
|
129
|
+
if not proj: raise HTTPException(404, "Not registered")
|
|
130
|
+
return {"features": db.get_features(proj["id"])}
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
@app.get("/function")
|
|
134
|
+
def explain(project_path: str, function_name: str, file: str = ""):
|
|
135
|
+
proj = db.get_project(project_path)
|
|
136
|
+
if not proj: raise HTTPException(404, "Not registered")
|
|
137
|
+
fn = db.get_function(proj["id"], function_name, file or None)
|
|
138
|
+
if not fn: raise HTTPException(404, f"Function '{function_name}' not found")
|
|
139
|
+
intents = db.get_intents(fn["id"])
|
|
140
|
+
decisions = db.get_decisions(fn["id"])
|
|
141
|
+
evolution = db.get_evolution(fn["id"])
|
|
142
|
+
for row in intents:
|
|
143
|
+
if row.get("claude_reasoning") is not None:
|
|
144
|
+
row["agent_reasoning"] = row["claude_reasoning"]
|
|
145
|
+
return {**dict(fn), "intents": intents, "decisions": decisions, "evolution": evolution}
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
@app.post("/search")
|
|
149
|
+
def search(req: SearchReq):
|
|
150
|
+
proj = db.get_project(req.project_path)
|
|
151
|
+
if not proj:
|
|
152
|
+
raise HTTPException(404, "Not registered")
|
|
153
|
+
|
|
154
|
+
mode = req.mode
|
|
155
|
+
if mode == "semantic":
|
|
156
|
+
results, available = emb.semantic_search(proj["id"], req.query, limit=req.limit)
|
|
157
|
+
if not available:
|
|
158
|
+
raise HTTPException(422, "sentence-transformers not installed. Run: pip install sentence-transformers numpy")
|
|
159
|
+
mode_used = "semantic"
|
|
160
|
+
elif mode == "hybrid":
|
|
161
|
+
results, mode_used = emb.hybrid_search(
|
|
162
|
+
proj["id"], req.query, limit=req.limit, semantic_weight=req.semantic_weight
|
|
163
|
+
)
|
|
164
|
+
else:
|
|
165
|
+
results = db.search_intents(proj["id"], req.query)[: req.limit]
|
|
166
|
+
mode_used = "keyword"
|
|
167
|
+
|
|
168
|
+
return {"query": req.query, "mode": mode_used, "results": results}
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
@app.post("/embed", status_code=202)
|
|
172
|
+
def embed_intents(project_path: str, background_tasks: BackgroundTasks, model: str = emb.DEFAULT_MODEL):
|
|
173
|
+
"""Start embedding in the background. Returns a job_id to poll with GET /embed/{job_id}."""
|
|
174
|
+
proj = db.get_project(project_path)
|
|
175
|
+
if not proj:
|
|
176
|
+
raise HTTPException(404, "Not registered")
|
|
177
|
+
job_id = uuid.uuid4().hex[:10]
|
|
178
|
+
_embed_jobs[job_id] = {"status": "running", "project_path": project_path, "model": model}
|
|
179
|
+
|
|
180
|
+
def _run():
|
|
181
|
+
try:
|
|
182
|
+
result = emb.embed_project(proj["id"], model_name=model)
|
|
183
|
+
_embed_jobs[job_id] = {"status": "done", **result}
|
|
184
|
+
except Exception as e:
|
|
185
|
+
_embed_jobs[job_id] = {"status": "error", "error": str(e)}
|
|
186
|
+
|
|
187
|
+
background_tasks.add_task(_run)
|
|
188
|
+
return {"job_id": job_id, "status": "running"}
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
@app.get("/embed/{job_id}")
|
|
192
|
+
def embed_status(job_id: str):
|
|
193
|
+
"""Poll the status of a background embed job."""
|
|
194
|
+
job = _embed_jobs.get(job_id)
|
|
195
|
+
if not job:
|
|
196
|
+
raise HTTPException(404, f"Job '{job_id}' not found")
|
|
197
|
+
return job
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
@app.get("/stats")
|
|
201
|
+
def stats(project_path: str):
|
|
202
|
+
proj = db.get_project(project_path)
|
|
203
|
+
if not proj: raise HTTPException(404, "Not registered")
|
|
204
|
+
cmap = db.get_codebase_map(proj["id"])
|
|
205
|
+
total = cmap["total_functions"]
|
|
206
|
+
annotated = cmap["annotated"]
|
|
207
|
+
backlog = cmap.get("hook_backlog") or []
|
|
208
|
+
return {
|
|
209
|
+
"total": total,
|
|
210
|
+
"annotated": annotated,
|
|
211
|
+
"coverage": round(annotated / total * 100, 1) if total else 0,
|
|
212
|
+
"features": len(cmap["features"]),
|
|
213
|
+
"unannotated_files": cmap["unannotated_files"],
|
|
214
|
+
"hook_backlog": backlog,
|
|
215
|
+
"pending_hook_files": len(backlog),
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
@app.get("/graph")
|
|
220
|
+
def intent_graph(project_path: str):
|
|
221
|
+
"""ReactFlow nodes + edges coloured by annotation status and feature."""
|
|
222
|
+
proj = db.get_project(project_path)
|
|
223
|
+
if not proj: raise HTTPException(404, "Not registered")
|
|
224
|
+
|
|
225
|
+
cmap = db.get_codebase_map(proj["id"])
|
|
226
|
+
features = {f["title"]: i for i, f in enumerate(cmap["features"])}
|
|
227
|
+
|
|
228
|
+
FEATURE_PALETTE = [
|
|
229
|
+
"#388bfd","#3fb950","#d29922","#bc8cff","#39d353",
|
|
230
|
+
"#f0883e","#58a6ff","#f85149","#79c0ff","#56d364",
|
|
231
|
+
]
|
|
232
|
+
|
|
233
|
+
nodes, edges = [], []
|
|
234
|
+
fn_index: dict[str, int] = {}
|
|
235
|
+
i = 0
|
|
236
|
+
|
|
237
|
+
for file, fns in cmap["by_file"].items():
|
|
238
|
+
for fn in fns:
|
|
239
|
+
node_id = fn["qualname"]
|
|
240
|
+
fn_index[fn["qualname"]] = i
|
|
241
|
+
|
|
242
|
+
# figure out feature colour
|
|
243
|
+
intent = fn.get("intent")
|
|
244
|
+
color = "#484f58" # unannotated
|
|
245
|
+
if intent:
|
|
246
|
+
color = "#3fb950" # annotated but no feature
|
|
247
|
+
|
|
248
|
+
nodes.append({
|
|
249
|
+
"id": node_id,
|
|
250
|
+
"type": "intentNode",
|
|
251
|
+
"data": {
|
|
252
|
+
"label": fn["name"],
|
|
253
|
+
"qualname": fn["qualname"],
|
|
254
|
+
"file": fn["file"],
|
|
255
|
+
"has_intent": fn["has_intent"],
|
|
256
|
+
"exists_because": intent["user_request"] if intent else None,
|
|
257
|
+
"confidence": intent["confidence"] if intent else None,
|
|
258
|
+
"color": color,
|
|
259
|
+
},
|
|
260
|
+
"position": {"x": (i % 6) * 280, "y": (i // 6) * 130},
|
|
261
|
+
})
|
|
262
|
+
i += 1
|
|
263
|
+
|
|
264
|
+
seen_edges = set()
|
|
265
|
+
for file, fns in cmap["by_file"].items():
|
|
266
|
+
pass # call graph edges would come from extractor — omitted to keep response lean
|
|
267
|
+
|
|
268
|
+
return {"nodes": nodes, "edges": edges}
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
# serve built UI
|
|
272
|
+
UI_DIST = Path(__file__).parent.parent / "ui" / "dist"
|
|
273
|
+
if UI_DIST.exists():
|
|
274
|
+
app.mount("/assets", StaticFiles(directory=UI_DIST / "assets"), name="assets")
|
|
275
|
+
@app.get("/{full_path:path}")
|
|
276
|
+
def serve_ui(full_path: str):
|
|
277
|
+
return FileResponse(UI_DIST / "index.html")
|
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: own-your-code
|
|
3
|
+
Version: 0.1.3
|
|
4
|
+
Summary: Own Your Code — MCP server + UI: record why each function exists, tradeoffs, and evolution (SQLite)
|
|
5
|
+
Project-URL: Repository, https://github.com/khirodsahoo93/mcp-own-your-code
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Keywords: codebase,documentation,intent,mcp,sqlite
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Requires-Dist: fastapi>=0.115.0
|
|
19
|
+
Requires-Dist: mcp>=1.0.0
|
|
20
|
+
Requires-Dist: pydantic>=2.0.0
|
|
21
|
+
Requires-Dist: uvicorn[standard]>=0.32.0
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: httpx>=0.27.0; extra == 'dev'
|
|
24
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
25
|
+
Requires-Dist: ruff>=0.4.0; extra == 'dev'
|
|
26
|
+
Provides-Extra: full
|
|
27
|
+
Requires-Dist: numpy>=1.26.0; extra == 'full'
|
|
28
|
+
Requires-Dist: sentence-transformers>=2.7.0; extra == 'full'
|
|
29
|
+
Requires-Dist: tree-sitter-go>=0.23.0; extra == 'full'
|
|
30
|
+
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'full'
|
|
31
|
+
Requires-Dist: tree-sitter>=0.23.0; extra == 'full'
|
|
32
|
+
Provides-Extra: multilang
|
|
33
|
+
Requires-Dist: tree-sitter-go>=0.23.0; extra == 'multilang'
|
|
34
|
+
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'multilang'
|
|
35
|
+
Requires-Dist: tree-sitter>=0.23.0; extra == 'multilang'
|
|
36
|
+
Provides-Extra: semantic
|
|
37
|
+
Requires-Dist: numpy>=1.26.0; extra == 'semantic'
|
|
38
|
+
Requires-Dist: sentence-transformers>=2.7.0; extra == 'semantic'
|
|
39
|
+
Description-Content-Type: text/markdown
|
|
40
|
+
|
|
41
|
+
# Own Your Code
|
|
42
|
+
|
|
43
|
+
**A living intent ledger for your codebase.**
|
|
44
|
+
|
|
45
|
+
Own Your Code captures the *why* behind every function — user requests, tradeoffs, decisions, and evolution — recorded via MCP as you work. Search by keyword or semantic similarity. Browse in a React UI or query the MCP server directly.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## The problem
|
|
50
|
+
|
|
51
|
+
Code is easy to read. It's impossible to understand.
|
|
52
|
+
|
|
53
|
+
You can read `hybrid_search()` in 5 minutes and know what it does. You can't know:
|
|
54
|
+
- Why cosine similarity instead of BM25?
|
|
55
|
+
- Was keyword-only search tried and rejected?
|
|
56
|
+
- What user request triggered this function?
|
|
57
|
+
- How did it behave before the last refactor?
|
|
58
|
+
|
|
59
|
+
That context lives in someone's head, a Slack thread, or nowhere.
|
|
60
|
+
|
|
61
|
+
**Own Your Code captures it at the moment it's created — while you’re implementing the change.**
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Features
|
|
66
|
+
|
|
67
|
+
- **Intent recording** — `record_intent` captures user request, reasoning, implementation notes, and confidence (typically from your MCP workflow).
|
|
68
|
+
- **Decision log** — tradeoffs, alternatives considered, constraints that forced a choice.
|
|
69
|
+
- **Evolution timeline** — every behavioral change with the reason and triggering request.
|
|
70
|
+
- **Multi-language AST indexing** — Python, TypeScript, JavaScript, Go. Pluggable extractor architecture.
|
|
71
|
+
- **Semantic search** — vector embeddings via `sentence-transformers`. Find `charge_card` by searching "what handles payments?".
|
|
72
|
+
- **Hybrid search** — merges keyword rank + semantic cosine score with tunable weight.
|
|
73
|
+
- **React UI** — Intent Map, Feature clusters, Search tab (keyword/semantic/hybrid), coverage bar, function detail panel.
|
|
74
|
+
- **MCP server** — works with any host that supports the Model Context Protocol.
|
|
75
|
+
- **FastAPI REST backend** — full API, suitable for team deployment.
|
|
76
|
+
- **Production-ready** — API key auth, SQLite WAL mode, configurable CORS, background embed jobs, 47 tests.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Quick start
|
|
81
|
+
|
|
82
|
+
### 1. Install (pick one)
|
|
83
|
+
|
|
84
|
+
**PyPI (after you publish, or use TestPyPI):**
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
pipx install own-your-code # recommended — puts own-your-code-mcp on PATH
|
|
88
|
+
own-your-code install # merges MCP config (see platform IDs below)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
python3 -m pip install own-your-code
|
|
93
|
+
own-your-code install --platform editor-a
|
|
94
|
+
own-your-code install --platform editor-b
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**npm (wrapper — still requires Python 3.11+ on PATH):**
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
npx own-your-code-mcp install
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
This runs `pip install -U own-your-code` if needed, then the same `own-your-code install` as above. Publish the shim from `npm/own-your-code-mcp/` to the npm registry when you are ready.
|
|
104
|
+
|
|
105
|
+
Use **`own-your-code-mcp` on PATH** (pipx/pip) for the actual MCP stdio server. The npm package is mainly so people who live in Node can run **`npx … install`** without memorizing pip; running MCP through `npx` is possible (`bin/mcp-shim.cjs`) but adds latency — prefer the Python binary when you can.
|
|
106
|
+
|
|
107
|
+
**From source:**
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
git clone https://github.com/khirodsahoo93/mcp-own-your-code
|
|
111
|
+
cd mcp-own-your-code
|
|
112
|
+
python -m venv .venv && source .venv/bin/activate
|
|
113
|
+
pip install -e .
|
|
114
|
+
|
|
115
|
+
# With semantic search support
|
|
116
|
+
pip install -e ".[semantic]"
|
|
117
|
+
|
|
118
|
+
# With multi-language AST support (TypeScript, Go)
|
|
119
|
+
pip install -e ".[full]"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Manual JSON fragment (if you skip `install`):
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
own-your-code print-config
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**uv users:** if `own-your-code-mcp` is not on PATH but `uvx` is, `own-your-code install` writes a block that runs `uvx --from own-your-code own-your-code-mcp` (once the package is on PyPI).
|
|
129
|
+
|
|
130
|
+
**`own-your-code install --platform` IDs** — each maps to a known config location on disk (see `src/cli.py` for exact paths). Use `all` to update every configured location.
|
|
131
|
+
|
|
132
|
+
### 2. Add to your MCP host
|
|
133
|
+
|
|
134
|
+
After `own-your-code install`, restart the editor. To configure by hand from a git checkout:
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"mcpServers": {
|
|
139
|
+
"own-your-code": {
|
|
140
|
+
"command": "/path/to/.venv/bin/python",
|
|
141
|
+
"args": ["-m", "src.server"],
|
|
142
|
+
"cwd": "/path/to/mcp-own-your-code"
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Or if installed as a package:
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"mcpServers": {
|
|
153
|
+
"own-your-code": {
|
|
154
|
+
"command": "own-your-code-mcp"
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### 3. Register your project
|
|
161
|
+
|
|
162
|
+
From your MCP client:
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
register_project path="/path/to/your/project"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
This scans all Python, TypeScript, JavaScript, and Go files and indexes every function.
|
|
169
|
+
|
|
170
|
+
### 4. Start building
|
|
171
|
+
|
|
172
|
+
As you write code, use `record_intent` from MCP (manually or via your host’s automation):
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
record_intent
|
|
176
|
+
project_path="/path/to/your/project"
|
|
177
|
+
file="src/auth.py"
|
|
178
|
+
function_name="verify_token"
|
|
179
|
+
user_request="Add JWT verification so the API rejects unsigned requests"
|
|
180
|
+
reasoning="Using PyJWT with RS256. Chose asymmetric keys so the public key can be distributed to services without exposing the signing key."
|
|
181
|
+
decisions=[{"decision": "RS256 over HS256", "reason": "Asymmetric — services can verify without the secret", "alternatives": ["HS256"]}]
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### 5. Open the UI
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
uvicorn api.main:app --reload --port 8002
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Open [http://localhost:8002](http://localhost:8002).
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## MCP tools
|
|
195
|
+
|
|
196
|
+
| Tool | Description |
|
|
197
|
+
|------|-------------|
|
|
198
|
+
| `register_project` | Scan and index a codebase (Python, TypeScript, JavaScript, Go) |
|
|
199
|
+
| `record_intent` | Record why a function exists — user request, reasoning, decisions |
|
|
200
|
+
| `record_evolution` | Log a behavioral change with the reason it happened |
|
|
201
|
+
| `explain_function` | Get the full story: intent, decisions, evolution timeline |
|
|
202
|
+
| `find_by_intent` | Search by keyword, semantic similarity, or hybrid |
|
|
203
|
+
| `embed_intents` | Backfill vector embeddings for semantic search |
|
|
204
|
+
| `get_codebase_map` | Full structured map: coverage, hook backlog, functions by file |
|
|
205
|
+
| `get_evolution` | Timeline of changes for a specific function |
|
|
206
|
+
| `annotate_existing` | Retroactively infer intents on a legacy codebase |
|
|
207
|
+
| `mark_file_reviewed` | Clear hook backlog for a file without adding intent |
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## REST API
|
|
212
|
+
|
|
213
|
+
| Method | Endpoint | Description |
|
|
214
|
+
|--------|----------|-------------|
|
|
215
|
+
| `GET` | `/health` | Health check |
|
|
216
|
+
| `GET` | `/projects` | List registered projects |
|
|
217
|
+
| `POST` | `/register` | Register and index a project |
|
|
218
|
+
| `GET` | `/map` | Full codebase map (supports `?file=` filter) |
|
|
219
|
+
| `GET` | `/function` | Intent, decisions, evolution for one function |
|
|
220
|
+
| `POST` | `/search` | Search intents (keyword / semantic / hybrid) |
|
|
221
|
+
| `POST` | `/embed` | Start background embedding job (returns `job_id`) |
|
|
222
|
+
| `GET` | `/embed/{job_id}` | Poll embedding job status |
|
|
223
|
+
| `GET` | `/stats` | Coverage and hook backlog summary |
|
|
224
|
+
| `GET` | `/features` | Feature clusters |
|
|
225
|
+
| `GET` | `/graph` | ReactFlow-compatible node graph |
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## Search modes
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
# Keyword — fast LIKE search over intent text
|
|
233
|
+
find_by_intent project_path="..." query="authentication" mode="keyword"
|
|
234
|
+
|
|
235
|
+
# Semantic — vector cosine similarity (run embed_intents first)
|
|
236
|
+
find_by_intent project_path="..." query="what handles retries?" mode="semantic"
|
|
237
|
+
|
|
238
|
+
# Hybrid — merges keyword rank + semantic score
|
|
239
|
+
find_by_intent project_path="..." query="payment processing" mode="hybrid" semantic_weight=0.6
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Via REST:
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
curl -X POST http://localhost:8002/search \
|
|
246
|
+
-H "Content-Type: application/json" \
|
|
247
|
+
-d '{"project_path": "/my/project", "query": "what handles payments?", "mode": "hybrid"}'
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Multi-language support
|
|
253
|
+
|
|
254
|
+
| Language | Parser | Fallback |
|
|
255
|
+
|----------|--------|---------|
|
|
256
|
+
| Python | `ast` (stdlib) | — |
|
|
257
|
+
| TypeScript / JavaScript | `tree-sitter-javascript` | regex |
|
|
258
|
+
| Go | `tree-sitter-go` | regex |
|
|
259
|
+
|
|
260
|
+
Configure indexing:
|
|
261
|
+
|
|
262
|
+
```json
|
|
263
|
+
{
|
|
264
|
+
"path": "/my/project",
|
|
265
|
+
"languages": ["python", "typescript"],
|
|
266
|
+
"include_globs": ["src/**/*.ts", "src/**/*.py"],
|
|
267
|
+
"ignore_dirs": ["vendor", "generated"]
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## Production deployment
|
|
274
|
+
|
|
275
|
+
### Environment variables
|
|
276
|
+
|
|
277
|
+
| Variable | Default | Description |
|
|
278
|
+
|----------|---------|-------------|
|
|
279
|
+
| `OWN_YOUR_CODE_DB` | `owns.db` | Path to SQLite file |
|
|
280
|
+
| `OWN_YOUR_CODE_API_KEY` | *(unset)* | Require `X-Api-Key` header. Leave unset for local use. |
|
|
281
|
+
| `OWN_YOUR_CODE_CORS_ORIGINS` | `*` | Comma-separated allowed origins |
|
|
282
|
+
| `OWN_YOUR_CODE_EMBED_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model name |
|
|
283
|
+
|
|
284
|
+
### Docker
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
docker compose up
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Or standalone:
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
docker build -t own-your-code .
|
|
294
|
+
docker run -p 8002:8002 \
|
|
295
|
+
-e OWN_YOUR_CODE_API_KEY=your-secret \
|
|
296
|
+
-e OWN_YOUR_CODE_CORS_ORIGINS=https://yourapp.com \
|
|
297
|
+
-v $(pwd)/data:/data \
|
|
298
|
+
-e OWN_YOUR_CODE_DB=/data/owns.db \
|
|
299
|
+
own-your-code
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### Render / Fly.io
|
|
303
|
+
|
|
304
|
+
A `render.yaml` is included. Set `OWN_YOUR_CODE_API_KEY` and `OWN_YOUR_CODE_DB` as environment variables in your deployment dashboard.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## Post-write hook
|
|
309
|
+
|
|
310
|
+
The post-write hook fires when your editor saves a file and records it in the backlog. Any file written without a subsequent `record_intent` appears in `get_codebase_map` as pending.
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
# Install the hook script for non-pip use
|
|
314
|
+
cp hooks/post_write.py .git/hooks/post-write && chmod +x .git/hooks/post-write
|
|
315
|
+
|
|
316
|
+
# Or use the installed entry point
|
|
317
|
+
own-your-code-hook
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
## Development
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
# Install dev dependencies
|
|
326
|
+
pip install -e ".[dev,full]"
|
|
327
|
+
|
|
328
|
+
# Run tests
|
|
329
|
+
pytest
|
|
330
|
+
|
|
331
|
+
# Lint
|
|
332
|
+
ruff check src/ api/ tests/
|
|
333
|
+
|
|
334
|
+
# Build UI
|
|
335
|
+
cd ui && npm install && npm run build
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
CI runs on Python 3.11, 3.12, and 3.13.
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Schema
|
|
343
|
+
|
|
344
|
+
SQLite. Tables:
|
|
345
|
+
|
|
346
|
+
| Table | Purpose |
|
|
347
|
+
|-------|---------|
|
|
348
|
+
| `projects` | Registered codebase roots |
|
|
349
|
+
| `functions` | Every known function (AST-extracted) |
|
|
350
|
+
| `intents` | Why a function exists — user request, reasoning, confidence |
|
|
351
|
+
| `intent_embeddings` | Vector blobs for semantic search (schema v2) |
|
|
352
|
+
| `decisions` | Tradeoffs and alternatives considered |
|
|
353
|
+
| `evolution` | Timeline of behavioral changes |
|
|
354
|
+
| `features` | High-level feature labels |
|
|
355
|
+
| `feature_links` | Many-to-many: functions ↔ features |
|
|
356
|
+
| `hook_events` | Files written by editor but not yet annotated |
|
|
357
|
+
|
|
358
|
+
Schema version tracked via `PRAGMA user_version`. Migrations are safe to run on existing databases.
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
## Publishing (maintainers)
|
|
363
|
+
|
|
364
|
+
### One-time setup
|
|
365
|
+
|
|
366
|
+
1. **PyPI** — Create the project `own-your-code` on [pypi.org](https://pypi.org). Under **Manage → Publishing**, add a **trusted publisher** for this GitHub repo and workflow **`.github/workflows/release.yml`** (see [PyPI docs](https://docs.pypi.org/trusted-publishers/)).
|
|
367
|
+
2. **npm** — Log in locally (`npm login`) once, or create a granular **Automation** token and add it as the GitHub secret **`NPM_TOKEN`** for this repository.
|
|
368
|
+
|
|
369
|
+
### Automated (recommended)
|
|
370
|
+
|
|
371
|
+
Push a **semver tag** after bumping `version` in `pyproject.toml` and `npm/own-your-code-mcp/package.json`:
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
# bump versions first, commit, then:
|
|
375
|
+
git tag v0.1.0
|
|
376
|
+
git push origin main && git push origin v0.1.0
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
GitHub Actions **Release** workflow uploads the wheel + sdist to **PyPI** and publishes **`own-your-code-mcp`** to npm.
|
|
380
|
+
|
|
381
|
+
### Manual
|
|
382
|
+
|
|
383
|
+
```bash
|
|
384
|
+
python3 -m pip install build twine
|
|
385
|
+
python3 -m build
|
|
386
|
+
TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-YOUR_PYPI_API_TOKEN python3 -m twine upload dist/*
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
```bash
|
|
390
|
+
cd npm/own-your-code-mcp
|
|
391
|
+
npm publish --access public
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
## License
|
|
395
|
+
|
|
396
|
+
MIT
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
api/__init__.py,sha256=3QSkCx7ORWq_qIrtudYk1Ey39DlliYGIQHewa2v135s,38
|
|
2
|
+
api/main.py,sha256=-vI887qYw9a3ZTpC_IYpDwvP0NwPje3HZpb8nAD1IuA,9953
|
|
3
|
+
src/__init__.py,sha256=9ExkN107xEM1KrR7S31MneKnEC2IMZQ3v70ueM_Obag,57
|
|
4
|
+
src/cli.py,sha256=S0DUl7xSkFeYWdidSZnOkVsaOljiuzuQCuPKbMM20mk,5449
|
|
5
|
+
src/db.py,sha256=3SnjpEpvgB97DXdQHoD0EbaJJxZPVGTzF5V_V5OsR4A,21700
|
|
6
|
+
src/embeddings.py,sha256=IRA9eLI8hvQh8rr0mPofbBjg3W-h1OtxL65hpjydHOA,7381
|
|
7
|
+
src/extractor.py,sha256=1fh0O_grn1erjS3VX4vk1IdLqvWJsza1yftGDbKXKoc,6512
|
|
8
|
+
src/post_write_hook.py,sha256=JvMGkKOWf71tBSp67QSVR_N41rqkjK5Nb5PBu9l8Csk,1925
|
|
9
|
+
src/server.py,sha256=_raaDk0UR1HK7SNdhHGIg6eojtXCje6I0R21cBULizg,29058
|
|
10
|
+
src/extractors/__init__.py,sha256=buFheF-09XS2QsdIbWetcoYI7lhYfHRXd2stT9xJeQY,1213
|
|
11
|
+
src/extractors/base.py,sha256=vkl0HrFrrSr7VA4Al5pF7dLz1qqmSDd38oYsfRzJDa8,1554
|
|
12
|
+
src/extractors/go_extractor.py,sha256=oCkLTEZQwrfexOv0DZKe6loh6D-sIwuv-TUoa3jY71I,5460
|
|
13
|
+
src/extractors/python_extractor.py,sha256=7LnX364VUvvGDrlFgnf4qRUcoHcmVoP6sMwgq8-_W7I,563
|
|
14
|
+
src/extractors/typescript_extractor.py,sha256=R0xQaxUo3bjphqX-4ELdWmx5iJVJ2kwACFXdeK71mYc,5961
|
|
15
|
+
own_your_code-0.1.3.dist-info/METADATA,sha256=3acAZzEmBD_ybDbDdi8txFNEhOkpzRHBz1_LTD4yfrI,12785
|
|
16
|
+
own_your_code-0.1.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
|
|
17
|
+
own_your_code-0.1.3.dist-info/entry_points.txt,sha256=5vIpnbN6LRlnaYcPN6GrE8jfx11bmLnFNjAIEFzD7Ms,129
|
|
18
|
+
own_your_code-0.1.3.dist-info/licenses/LICENSE,sha256=F12SGcNKMiUvkSX_n9QSe-IwAw22i5d0szKsnTFMka4,1063
|
|
19
|
+
own_your_code-0.1.3.dist-info/RECORD,,
|