purecontext-mcp 1.1.0 → 1.1.2

package/docs/18-git-history.md

@@ -0,0 +1,157 @@
+# Git & History Integration
+
+
+Git integration gives agents and the Web UI access to symbol-level history, diff analysis, and churn metrics — without requiring agents to run git commands themselves.
+
+---
+
+## How it works
+
+During indexing, PureContext walks `git log` and maps commits to symbols using byte-range overlap:
+
+1. For each commit, `git diff` is parsed to identify changed byte ranges per file
+2. These ranges are matched against indexed symbol byte offsets
+3. The mapping is stored in the `git_metadata` table in SQLite
+
+This means you can ask "which commits touched `authenticateUser`?" and get an answer from the index — no git subprocess needed at query time.
+
+---
+
+## Requirements
+
+- `git` must be on PATH
+- The indexed project must be a git repository
+
+---
+
+## Configuration
+
+```json
+{
+  "git": {
+    "enabled": true,
+    "maxCommits": 500,
+    "includeMergeCommits": false,
+    "branches": ["main", "develop"]
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `git.enabled` | `true` | Enable git metadata indexing (if repo is a git repo) |
+| `git.maxCommits` | `500` | Maximum commits to walk back from HEAD |
+| `git.includeMergeCommits` | `false` | Include merge commits (usually noise) |
+| `git.branches` | `["main"]` | Branches to index history from |
+
+---
+
+## `get_symbol_history`
+
+Symbol-level git history: which commits touched a symbol, and how.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `symbolId` | `string` | required | Symbol to query |
+| `limit` | `number` | `20` | Max commits to return |
+
+**Response:**
+
+```json
+{
+  "symbol": {
+    "name": "authenticateUser",
+    "filePath": "src/auth/validator.ts"
+  },
+  "history": [
+    {
+      "hash": "a1b2c3d4",
+      "author": "alice",
+      "date": "2026-04-15T10:30:00Z",
+      "message": "Add MFA support to authenticateUser",
+      "diff": "@@ -12,6 +12,14 @@ ...",
+      "linesAdded": 14,
+      "linesRemoved": 3
+    }
+  ]
+}
+```
+
+**Use cases:**
+- "When was this function last changed?"
+- "Who introduced this code?"
+- "What changed in this function over the last month?"
+
+---
+
+## `get_churn_metrics`
+
+File and symbol churn metrics — how often things change.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `filePath` | `string` | — | Scope to one file (optional) |
+| `since` | `string` | — | ISO 8601 date — look back from this date |
+
+**Response:**
+
+```json
+{
+  "files": [
+    {
+      "filePath": "src/auth/validator.ts",
+      "commits": 47,
+      "linesChanged": 820,
+      "authors": ["alice", "bob", "charlie"],
+      "churnScore": 8.4,
+      "lastChanged": "2026-04-20T14:00:00Z"
+    }
+  ]
+}
+```
+
+**Interpreting `churnScore`:** Normalized metric (0–10+). High churn (> 6) indicates either: active development, frequent bug fixes, or instability. Use alongside quality metrics to distinguish "active feature" from "unstable code".
+
+---
+
+## PR / diff analysis
+
+Analyze what a branch or commit range changes at the symbol level:
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repoId` | `string` | Target repository |
+| `base` | `string` | Base branch or commit hash |
+| `head` | `string` | Head branch or commit hash |
+
+**Response:** Symbols added, modified, deleted; blast radius of changed symbols.
+
+**Use case:** Before reviewing a PR, call this to understand the symbol-level impact — not just which files changed, but which functions were modified and what else might be affected.
+
+---
+
+## Git history in the Web UI
+
+When git integration is enabled:
+
+- **Heatmap overlay** in the file tree shows churn data
+- **Symbol timeline** shows per-symbol history as a visual timeline
+- High-churn files appear in a "Hot files" panel in the dashboard
+
+---
+
+## Limitations
+
+- History is indexed up to `git.maxCommits` — commits older than that are not tracked
+- **Renames/moves:** git rename detection is best-effort. Symbols in renamed files start fresh history from the rename commit
+- **Merge commits:** excluded by default to avoid noise from merge-only diffs
+- **Rebased history:** rebase changes commit hashes — a re-index is needed to pick up rebased history accurately
+- Git submodules are not indexed

package/docs/19-cross-repo.md

@@ -0,0 +1,177 @@
+# Cross-Repo Intelligence
+
+
+Cross-repo tools let agents search across multiple indexed repositories simultaneously and find semantically similar code regardless of which repo it lives in.
+
+---
+
+## Overview
+
+When multiple repos are indexed (e.g., a microservices ecosystem or a monorepo with sub-projects), cross-repo tools provide a unified view. No special configuration is needed — all repos indexed in the same workspace are automatically eligible for cross-repo search.
+
+---
+
+## `search_cross_repo`
+
+Search symbols across multiple repos with a single query.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | `string` | required | Name fragment or natural language |
+| `repoIds` | `string[]` | — | Repos to search. Omit to search all repos in workspace. |
+| `kind` | `string` | — | Symbol kind filter |
+| `limit` | `number` | `20` | Max results |
+| `mode` | `string` | `"keyword"` | `"keyword"`, `"semantic"`, or `"hybrid"` |
+
+**Response:**
+
+```json
+{
+  "symbols": [
+    {
+      "id": "abc123",
+      "name": "authenticate",
+      "kind": "function",
+      "filePath": "src/auth/user.ts",
+      "repoId": "a1b2c3d4",
+      "repoPath": "/projects/user-service",
+      "signature": "function authenticate(token: string): Promise<User>",
+      "summary": "Validates JWT token and returns authenticated user."
+    },
+    {
+      "id": "def456",
+      "name": "authenticate",
+      "kind": "method",
+      "filePath": "app/services/auth_service.rb",
+      "repoId": "e5f6a7b8",
+      "repoPath": "/projects/api-gateway",
+      "signature": "def authenticate(credentials)",
+      "summary": "Rails service method for credential validation."
+    }
+  ]
+}
+```
+
+**Use cases:**
+- "Find all `authenticate` functions across my microservices"
+- "Which services have a `sendEmail` function?"
+- "Where is the `UserProfile` type defined across all repos?"
+
+---
+
+## `find_similar`
+
+Find semantically similar code across repos — detect duplication, discover existing implementations, find patterns.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `symbolId` | `string` | required | Reference symbol |
+| `repoId` | `string` | required | Repo of the reference symbol |
+| `searchRepoIds` | `string[]` | — | Repos to search (default: all) |
+| `minSimilarity` | `number` | `0.8` | Minimum cosine similarity (0–1) |
+| `limit` | `number` | `10` | Max results |
+
+**Response:**
+
+```json
+{
+  "reference": {
+    "name": "formatCurrency",
+    "repoId": "a1b2c3d4",
+    "filePath": "src/utils/format.ts"
+  },
+  "similar": [
+    {
+      "id": "xyz789",
+      "name": "formatMoney",
+      "repoId": "e5f6a7b8",
+      "repoPath": "/projects/billing-service",
+      "filePath": "lib/helpers/currency.rb",
+      "similarity": 0.94,
+      "summary": "Formats a decimal value as a localized currency string."
+    }
+  ]
+}
+```
+
+**Requires:** Semantic search enabled in config (`semantic.enabled: true` with a provider configured).
+
+**Use cases:**
+- "Is there already a `formatCurrency` function somewhere in our codebase before I write a new one?"
+- "Find all copy-pasted validation logic across repos"
+- "Discover shared utilities that should be extracted into a common library"
+
+---
+
+## Cross-repo dependency tracking
+
+Track import relationships that cross repo boundaries. For example, in a monorepo or workspace where packages import each other.
+
+Configure cross-repo dependencies in each project's `.purecontext.json`:
+
+```json
+{
+  "crossRepoDeps": ["@myorg/shared-utils", "@myorg/api-client"]
+}
+```
+
+When these packages are also indexed repos, `get_blast_radius` with `crossRepo: true` will follow the dependency chain across repo boundaries.
+
+---
+
+## MCP Resources
+
+In addition to MCP Tools, PureContext exposes **MCP Resources** — a push-based subscription model where agents can subscribe to symbol content and receive updates when it changes.
+
+### Resource URI format
+
+```
+purecontext://repo/{repoId}/symbol/{symbolId}
+```
+
+### Using MCP Resources
+
+List available resources:
+
+```
+GET purecontext://repo/{repoId}/symbols
+```
+
+Subscribe to a resource (supported by MCP clients that implement `resources/subscribe`):
+
+```json
+{
+  "method": "resources/subscribe",
+  "params": {
+    "uri": "purecontext://repo/a1b2c3d4/symbol/8f3a2c1d"
+  }
+}
+```
+
+The server sends a `resources/updated` notification whenever the symbol's source changes (detected by the file watcher).
+
+### Use cases for MCP Resources
+
+- Agents that monitor a critical function and react when it changes
+- Live documentation tools that stay in sync with the code
+- CI integrations that trigger when specific symbols are modified
+
+---
+
+## Setting up cross-repo search
+
+No special setup is required. Index each repo independently:
+
+```
+index_folder("/projects/user-service")
+index_folder("/projects/billing-service")
+index_folder("/projects/api-gateway")
+```
+
+Then use `search_cross_repo` or `find_similar` — they automatically search all indexed repos in the workspace.
+
+To restrict search to specific repos, pass their `repoIds` explicitly.

package/docs/20-architecture-analysis.md

@@ -0,0 +1,228 @@
+# AI-Powered Architecture Analysis
+
+
+Architecture analysis tools use the symbol graph and AI to surface quality metrics, detect anti-patterns, and generate documentation automatically.
+
+---
+
+## `get_quality_metrics`
+
+Per-file and per-symbol quality scores based on static analysis of the dependency graph and symbol data.
+
+**Parameters:** `{ repoId, filePath? }`
+
+**Response:**
+
+```json
+{
+  "files": [
+    {
+      "filePath": "src/auth/validator.ts",
+      "complexity": 6.2,
+      "coupling": {
+        "fanIn": 14,
+        "fanOut": 8
+      },
+      "cohesion": 0.71,
+      "docCoverage": 0.85,
+      "score": 72
+    }
+  ],
+  "summary": {
+    "averageScore": 68,
+    "worstFiles": ["src/legacy/processor.ts"],
+    "bestFiles": ["src/utils/format.ts"]
+  }
+}
+```
+
+**Metrics explained:**
+
+| Metric | Meaning | Good range |
+|--------|---------|-----------|
+| `complexity` | Average cyclomatic complexity per function | < 5 |
+| `coupling.fanIn` | Files that import this file | depends on role |
+| `coupling.fanOut` | Files this file imports | < 10 |
+| `cohesion` | How related the symbols in a file are (0–1) | > 0.6 |
+| `docCoverage` | % of exported symbols with non-empty summaries | > 0.8 |
+| `score` | Composite quality score (0–100) | > 70 |
+
+---
+
+## `detect_antipatterns`
+
+Scan a repo for common architectural anti-patterns.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `patterns` | `string[]` | all | Specific patterns to check. Omit for all. |
+
+**Available patterns:**
+
+| Pattern | Description |
+|---------|-------------|
+| `god-class` | Class with > 20 methods or > 15 imports |
+| `god-function` | Function with cyclomatic complexity > 15 |
+| `high-coupling` | File with fan-out > 20 |
+| `circular-deps` | Import cycles (A→B→C→A) |
+| `dead-code` | Exported symbols with no importers |
+| `missing-docs` | Exported symbols without summaries |
+| `inconsistent-naming` | Mixed camelCase/snake_case in a single file |
+| `deep-nesting` | Functions with nesting depth > 5 |
+
+**Response:**
+
+```json
+{
+  "issues": [
+    {
+      "pattern": "god-class",
+      "filePath": "src/legacy/UserManager.ts",
+      "symbolId": "abc123",
+      "symbolName": "UserManager",
+      "severity": "warning",
+      "description": "UserManager has 34 methods. Consider splitting into smaller, focused classes.",
+      "metrics": { "methodCount": 34 }
+    },
+    {
+      "pattern": "circular-deps",
+      "filePath": "src/core/index.ts",
+      "severity": "error",
+      "description": "Circular dependency: src/core/index.ts → src/utils/helpers.ts → src/core/index.ts",
+      "cycle": ["src/core/index.ts", "src/utils/helpers.ts"]
+    }
+  ],
+  "summary": {
+    "total": 12,
+    "errors": 2,
+    "warnings": 10
+  }
+}
+```
+
+---
+
+## `get_architecture_doc`
+
+Auto-generate an architecture summary for the repo — useful for onboarding, design reviews, or keeping architecture documentation current.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `format` | `string` | `"markdown"` | `"markdown"` or `"mermaid"` |
+
+**Response (markdown):**
+
+```json
+{
+  "doc": "# Architecture Overview\n\n## Entry Points\n...\n## Module Structure\n...\n## Key Dependencies\n..."
+}
+```
+
+**Response (mermaid):**
+
+```json
+{
+  "doc": "graph TD\n  A[src/index.ts] --> B[src/core/]\n  B --> C[src/handlers/]\n..."
+}
+```
+
+The generated document includes:
+- Top-level entry points
+- Module/layer breakdown
+- Key external dependencies
+- Framework adapters detected
+- High-level data flow
+
+This uses AI (the configured `ai.provider`) to summarize the graph structure into natural language. Requires `ai.allowRemoteAI: true`.
+
+---
+
+## Refactoring detector
+
+Identify candidates for refactoring based on size, coupling, and duplication.
+
+**Parameters:** `{ repoId }`
+
+**Response:**
+
+```json
+{
+  "candidates": [
+    {
+      "type": "extract-function",
+      "filePath": "src/auth/processor.ts",
+      "symbolId": "abc123",
+      "symbolName": "processAuthRequest",
+      "reason": "Function has 120 lines and cyclomatic complexity of 18. Consider extracting validation and transformation logic.",
+      "priority": "high"
+    },
+    {
+      "type": "extract-module",
+      "filePath": "src/utils/helpers.ts",
+      "reason": "File contains 45 symbols across 8 unrelated concerns. Consider splitting by domain.",
+      "priority": "medium"
+    },
+    {
+      "type": "deduplicate",
+      "symbols": [
+        { "repoId": "a1b2c3d4", "symbolId": "def456", "name": "formatDate" },
+        { "repoId": "a1b2c3d4", "symbolId": "ghi789", "name": "formatDateLegacy" }
+      ],
+      "similarity": 0.96,
+      "reason": "These two functions are 96% similar. Consider merging.",
+      "priority": "low"
+    }
+  ]
+}
+```
+
+---
+
+## Smart context bundling
+
+An AI-powered enhancement of `get_context_bundle` that uses quality metrics and churn data to prioritize what context to include within a token budget.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `symbolId` | `string` | required | Starting symbol |
+| `maxTokens` | `number` | `4000` | Token budget |
+| `strategy` | `string` | `"balanced"` | `"quality"`, `"churn"`, or `"balanced"` |
+
+Strategies:
+- **`quality`** — prioritize high-quality, well-documented dependencies
+- **`churn`** — prioritize recently changed dependencies (likely most relevant)
+- **`balanced`** — weighted combination of both
+
+---
+
+## Using analysis tools together
+
+A pre-refactoring workflow:
+
+```
+1. get_quality_metrics(repoId)
+   → Find the lowest-scoring files
+
+2. detect_antipatterns(repoId, patterns: ["god-class", "circular-deps"])
+   → Find structural issues in those files
+
+3. get_blast_radius(symbolId)
+   → Understand the impact scope before changing a god class
+
+4. get_architecture_doc(repoId, format: "mermaid")
+   → Generate a before-picture for the design doc
+
+5. (make the refactoring)
+
+6. detect_antipatterns(repoId)
+   → Verify the anti-patterns were resolved
+```