Metadata-Version: 2.4
Name: own-your-code
Version: 0.1.3
Summary: Own Your Code — MCP server + UI: record why each function exists, tradeoffs, and evolution (SQLite)
Project-URL: Repository, https://github.com/khirodsahoo93/mcp-own-your-code
License-Expression: MIT
License-File: LICENSE
Keywords: codebase,documentation,intent,mcp,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: numpy>=1.26.0; extra == 'full'
Requires-Dist: sentence-transformers>=2.7.0; extra == 'full'
Requires-Dist: tree-sitter-go>=0.23.0; extra == 'full'
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'full'
Requires-Dist: tree-sitter>=0.23.0; extra == 'full'
Provides-Extra: multilang
Requires-Dist: tree-sitter-go>=0.23.0; extra == 'multilang'
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'multilang'
Requires-Dist: tree-sitter>=0.23.0; extra == 'multilang'
Provides-Extra: semantic
Requires-Dist: numpy>=1.26.0; extra == 'semantic'
Requires-Dist: sentence-transformers>=2.7.0; extra == 'semantic'
Description-Content-Type: text/markdown

# Own Your Code

**A living intent ledger for your codebase.**

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.

---

## The problem

Code is easy to read. It's impossible to understand.

You can read `hybrid_search()` in 5 minutes and know what it does. You can't know:
- Why cosine similarity instead of BM25?
- Was keyword-only search tried and rejected?
- What user request triggered this function?
- How did it behave before the last refactor?

That context lives in someone's head, a Slack thread, or nowhere.

**Own Your Code captures it at the moment it's created — while you’re implementing the change.**

---

## Features

- **Intent recording** — `record_intent` captures user request, reasoning, implementation notes, and confidence (typically from your MCP workflow).
- **Decision log** — tradeoffs, alternatives considered, constraints that forced a choice.
- **Evolution timeline** — every behavioral change with the reason and triggering request.
- **Multi-language AST indexing** — Python, TypeScript, JavaScript, Go. Pluggable extractor architecture.
- **Semantic search** — vector embeddings via `sentence-transformers`. Find `charge_card` by searching "what handles payments?".
- **Hybrid search** — merges keyword rank + semantic cosine score with tunable weight.
- **React UI** — Intent Map, Feature clusters, Search tab (keyword/semantic/hybrid), coverage bar, function detail panel.
- **MCP server** — works with any host that supports the Model Context Protocol.
- **FastAPI REST backend** — full API, suitable for team deployment.
- **Production-ready** — API key auth, SQLite WAL mode, configurable CORS, background embed jobs, 47 tests.

---

## Quick start

### 1. Install (pick one)

**PyPI (after you publish, or use TestPyPI):**

```bash
pipx install own-your-code # recommended — puts own-your-code-mcp on PATH
own-your-code install               # merges MCP config (see platform IDs below)
```

```bash
python3 -m pip install own-your-code
own-your-code install --platform editor-a
own-your-code install --platform editor-b
```

**npm (wrapper — still requires Python 3.11+ on PATH):**

```bash
npx own-your-code-mcp install
```

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.

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.

**From source:**

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

# With semantic search support
pip install -e ".[semantic]"

# With multi-language AST support (TypeScript, Go)
pip install -e ".[full]"
```

Manual JSON fragment (if you skip `install`):

```bash
own-your-code print-config
```

**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).

**`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.

### 2. Add to your MCP host

After `own-your-code install`, restart the editor. To configure by hand from a git checkout:

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

Or if installed as a package:

```json
{
  "mcpServers": {
    "own-your-code": {
      "command": "own-your-code-mcp"
    }
  }
}
```

### 3. Register your project

From your MCP client:

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

This scans all Python, TypeScript, JavaScript, and Go files and indexes every function.

### 4. Start building

As you write code, use `record_intent` from MCP (manually or via your host’s automation):

```
record_intent
  project_path="/path/to/your/project"
  file="src/auth.py"
  function_name="verify_token"
  user_request="Add JWT verification so the API rejects unsigned requests"
  reasoning="Using PyJWT with RS256. Chose asymmetric keys so the public key can be distributed to services without exposing the signing key."
  decisions=[{"decision": "RS256 over HS256", "reason": "Asymmetric — services can verify without the secret", "alternatives": ["HS256"]}]
```

### 5. Open the UI

```bash
uvicorn api.main:app --reload --port 8002
```

Open [http://localhost:8002](http://localhost:8002).

---

## MCP tools

| Tool | Description |
|------|-------------|
| `register_project` | Scan and index a codebase (Python, TypeScript, JavaScript, Go) |
| `record_intent` | Record why a function exists — user request, reasoning, decisions |
| `record_evolution` | Log a behavioral change with the reason it happened |
| `explain_function` | Get the full story: intent, decisions, evolution timeline |
| `find_by_intent` | Search by keyword, semantic similarity, or hybrid |
| `embed_intents` | Backfill vector embeddings for semantic search |
| `get_codebase_map` | Full structured map: coverage, hook backlog, functions by file |
| `get_evolution` | Timeline of changes for a specific function |
| `annotate_existing` | Retroactively infer intents on a legacy codebase |
| `mark_file_reviewed` | Clear hook backlog for a file without adding intent |

---

## REST API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Health check |
| `GET` | `/projects` | List registered projects |
| `POST` | `/register` | Register and index a project |
| `GET` | `/map` | Full codebase map (supports `?file=` filter) |
| `GET` | `/function` | Intent, decisions, evolution for one function |
| `POST` | `/search` | Search intents (keyword / semantic / hybrid) |
| `POST` | `/embed` | Start background embedding job (returns `job_id`) |
| `GET` | `/embed/{job_id}` | Poll embedding job status |
| `GET` | `/stats` | Coverage and hook backlog summary |
| `GET` | `/features` | Feature clusters |
| `GET` | `/graph` | ReactFlow-compatible node graph |

---

## Search modes

```bash
# Keyword — fast LIKE search over intent text
find_by_intent project_path="..." query="authentication" mode="keyword"

# Semantic — vector cosine similarity (run embed_intents first)
find_by_intent project_path="..." query="what handles retries?" mode="semantic"

# Hybrid — merges keyword rank + semantic score
find_by_intent project_path="..." query="payment processing" mode="hybrid" semantic_weight=0.6
```

Via REST:

```bash
curl -X POST http://localhost:8002/search \
  -H "Content-Type: application/json" \
  -d '{"project_path": "/my/project", "query": "what handles payments?", "mode": "hybrid"}'
```

---

## Multi-language support

| Language | Parser | Fallback |
|----------|--------|---------|
| Python | `ast` (stdlib) | — |
| TypeScript / JavaScript | `tree-sitter-javascript` | regex |
| Go | `tree-sitter-go` | regex |

Configure indexing:

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

---

## Production deployment

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OWN_YOUR_CODE_DB` | `owns.db` | Path to SQLite file |
| `OWN_YOUR_CODE_API_KEY` | *(unset)* | Require `X-Api-Key` header. Leave unset for local use. |
| `OWN_YOUR_CODE_CORS_ORIGINS` | `*` | Comma-separated allowed origins |
| `OWN_YOUR_CODE_EMBED_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model name |

### Docker

```bash
docker compose up
```

Or standalone:

```bash
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` as environment variables in your deployment dashboard.

---

## Post-write hook

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.

```bash
# Install the hook script for non-pip use
cp hooks/post_write.py .git/hooks/post-write && chmod +x .git/hooks/post-write

# Or use the installed entry point
own-your-code-hook
```

---

## Development

```bash
# Install dev dependencies
pip install -e ".[dev,full]"

# Run tests
pytest

# Lint
ruff check src/ api/ tests/

# Build UI
cd ui && npm install && npm run build
```

CI runs on Python 3.11, 3.12, and 3.13.

---

## Schema

SQLite. Tables:

| Table | Purpose |
|-------|---------|
| `projects` | Registered codebase roots |
| `functions` | Every known function (AST-extracted) |
| `intents` | Why a function exists — user request, reasoning, confidence |
| `intent_embeddings` | Vector blobs for semantic search (schema v2) |
| `decisions` | Tradeoffs and alternatives considered |
| `evolution` | Timeline of behavioral changes |
| `features` | High-level feature labels |
| `feature_links` | Many-to-many: functions ↔ features |
| `hook_events` | Files written by editor but not yet annotated |

Schema version tracked via `PRAGMA user_version`. Migrations are safe to run on existing databases.

---

## Publishing (maintainers)

### One-time setup

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/)).
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.

### Automated (recommended)

Push a **semver tag** after bumping `version` in `pyproject.toml` and `npm/own-your-code-mcp/package.json`:

```bash
# bump versions first, commit, then:
git tag v0.1.0
git push origin main && git push origin v0.1.0
```

GitHub Actions **Release** workflow uploads the wheel + sdist to **PyPI** and publishes **`own-your-code-mcp`** to npm.

### Manual

```bash
python3 -m pip install build twine
python3 -m build
TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-YOUR_PYPI_API_TOKEN python3 -m twine upload dist/*
```

```bash
cd npm/own-your-code-mcp
npm publish --access public
```

## License

MIT
