@danielblomma/cortex-mcp 0.4.0

package/docs/MCP_MARKETPLACE.md

@@ -0,0 +1,160 @@
+# MCP Marketplace Submission
+
+## Package Information
+
+**Name:** `@danielblomma/cortex-mcp`  
+**Description:** Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.  
+**Author:** Daniel Blomma  
+**License:** MIT  
+**Repository:** https://github.com/DanielBlomma/cortex
+
+## MCP Server Details
+
+### Tools Provided
+
+1. **context.search**
+   - Semantic search across indexed entities (files, rules, ADRs)
+   - Hybrid ranking (semantic + graph + trust + recency)
+   - Optional content return for high-signal snippets
+
+2. **context.get_related**
+   - Graph-based entity relationships
+   - Finds connected rules/files/ADRs with optional edge details
+
+3. **context.get_rules**
+   - Active rules and architectural decisions
+   - Scope-based filtering
+
+4. **context.reload**
+   - Hot-reload graph after code changes
+
+### Advanced Features (Experimental)
+
+Cortex can extract function-level chunks and build call graphs in experimental builds:
+
+- `context.find_callers` - What calls this function?
+- `context.trace_calls` - What does this function call?
+- `context.impact_analysis` - What is impacted if this function changes?
+- Requires JavaScript/TypeScript codebase and semantic chunking/call graph indexing enabled.
+
+Note: these APIs are experimental and are not part of the stable tool contract in this submission.
+
+### Installation
+
+#### For MCP Marketplace Users
+
+```bash
+# Install CLI globally
+npm i -g @danielblomma/cortex-mcp
+
+# Navigate to your project
+cd ~/my-project
+
+# Initialize Cortex in your project
+cortex init --bootstrap
+```
+
+This will:
+- Create `.context/` directory with graph schema
+- Set up MCP server for Claude Desktop/Code
+- Start background sync for automatic updates
+- Build a local context graph for indexed files/rules/ADRs
+
+#### Manual MCP Configuration
+
+If `cortex init` doesn't auto-register, add to Claude's MCP config:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "command": "cortex",
+      "args": ["mcp"],
+      "env": {
+        "CORTEX_PROJECT_ROOT": "/absolute/path/to/your-project"
+      }
+    }
+  }
+}
+```
+
+**Codex** (`~/.config/codex/mcp-config.json`):
+```json
+{
+  "mcpServers": {
+    "cortex-myproject": {
+      "command": "cortex",
+      "args": ["mcp"],
+      "cwd": "/absolute/path/to/your-project"
+    }
+  }
+}
+```
+
+### Usage
+
+Once installed and initialized, Cortex tools are available in Claude:
+
+```
+"Find files that handle authentication"
+"Show related files for this ADR"
+"What are the active architectural rules for this API?"
+```
+
+### Key Features
+
+- **Semantic search**: ranked retrieval across source files, rules and ADRs
+- **Graph relationships**: quickly discover related entities and constraints
+- **Experimental call graph APIs**: function caller/callee and impact traversal in semantic chunking builds
+- **Local & private**: All data stays on your machine
+- **Incremental updates**: Background sync keeps context fresh
+- **Flexible ingestion**: configurable source paths and ranking signals
+
+### Requirements
+
+- Node.js 18+
+- Git repository (for change tracking)
+- ~50MB disk space per project
+
+### Unique Value Proposition
+
+Unlike other MCP servers that provide external data (GitHub, web search), Cortex provides **deep, structured knowledge of YOUR codebase**:
+
+- Search with semantic ranking across files, rules, and ADRs
+- Understand rule and ADR dependencies in your repo
+- Enforce architectural rules and ADRs
+- Context that evolves with your code
+
+Perfect for:
+- Large codebases where plain keyword search is not enough
+- Refactoring guided by rule and ADR context
+- Onboarding (architectural rules, design decisions)
+- Code review (what constraints and related entities apply?)
+
+### Limitations
+
+- **Setup required**: Not instant plug-and-play (needs `cortex init`)
+- **Per-project**: Each repo needs its own Cortex instance
+- **Local only**: No cloud sync (by design - your code stays private)
+
+### Support
+
+- Issues: https://github.com/DanielBlomma/cortex/issues
+- Docs: https://github.com/DanielBlomma/cortex/blob/main/README.md
+
+## Submission Checklist
+
+- [x] MCP SDK integration (JSON-RPC over stdio)
+- [x] Tools documented with schemas
+- [ ] npm package published (@danielblomma/cortex-mcp)
+- [x] Marketplace-ready README
+- [ ] Example usage screenshots/GIFs
+- [ ] Submit PR to modelcontextprotocol/servers
+
+## Next Steps
+
+1. Publish to npm as `@danielblomma/cortex-mcp`
+2. Test installation from marketplace perspective
+3. Submit to https://github.com/modelcontextprotocol/servers
+4. Add to Anthropic's community registry

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@danielblomma/cortex-mcp",
+  "version": "0.4.0",
+  "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
+  "type": "module",
+  "author": "Daniel Blomma",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DanielBlomma/cortex.git"
+  },
+  "homepage": "https://github.com/DanielBlomma/cortex",
+  "bugs": {
+    "url": "https://github.com/DanielBlomma/cortex/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "context",
+    "code-search",
+    "semantic-search",
+    "refactoring",
+    "claude",
+    "codex"
+  ],
+  "bin": {
+    "cortex": "bin/cortex.mjs"
+  },
+  "files": [
+    "bin",
+    "scaffold",
+    "README.md",
+    "docs/MCP_MARKETPLACE.md"
+  ],
+  "scripts": {
+    "test": "node tests/plan-state.test.mjs",
+    "prepublishOnly": "echo 'Ready to publish to npm'"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scaffold/.context/config.yaml

@@ -0,0 +1,21 @@
+repo_id: cortex
+source_paths:
+  - src
+  - docs
+  - design
+  - .context/notes
+  - .context/decisions
+  - README.md
+truth_order:
+  - ADR
+  - RULE
+  - CODE
+  - WIKI
+ranking:
+  semantic: 0.40
+  graph: 0.25
+  trust: 0.20
+  recency: 0.15
+runtime:
+  top_k: 5
+  include_uncertainties: true

package/scaffold/.context/ontology.cypher

@@ -0,0 +1,63 @@
+// Core node labels for v1
+CREATE NODE TABLE IF NOT EXISTS File(
+  id STRING,
+  path STRING,
+  kind STRING,
+  excerpt STRING,
+  checksum STRING,
+  updated_at STRING,
+  source_of_truth BOOL,
+  trust_level INT64,
+  status STRING,
+  PRIMARY KEY(id)
+);
+
+CREATE NODE TABLE IF NOT EXISTS Rule(
+  id STRING,
+  title STRING,
+  body STRING,
+  scope STRING,
+  priority INT64,
+  updated_at STRING,
+  source_of_truth BOOL,
+  trust_level INT64,
+  status STRING,
+  PRIMARY KEY(id)
+);
+
+CREATE NODE TABLE IF NOT EXISTS ADR(
+  id STRING,
+  path STRING,
+  title STRING,
+  body STRING,
+  decision_date STRING,
+  supersedes_id STRING,
+  source_of_truth BOOL,
+  trust_level INT64,
+  status STRING,
+  PRIMARY KEY(id)
+);
+
+CREATE NODE TABLE IF NOT EXISTS Chunk(
+  id STRING,
+  file_id STRING,
+  name STRING,
+  kind STRING,
+  signature STRING,
+  body STRING,
+  start_line INT64,
+  end_line INT64,
+  language STRING,
+  checksum STRING,
+  updated_at STRING,
+  trust_level INT64,
+  PRIMARY KEY(id)
+);
+
+// Core relation tables for v1
+CREATE REL TABLE IF NOT EXISTS IMPLEMENTS(FROM File TO Rule, note STRING);
+CREATE REL TABLE IF NOT EXISTS CONSTRAINS(FROM Rule TO File, note STRING);
+CREATE REL TABLE IF NOT EXISTS SUPERSEDES(FROM ADR TO ADR, reason STRING);
+CREATE REL TABLE IF NOT EXISTS DEFINES(FROM File TO Chunk);
+CREATE REL TABLE IF NOT EXISTS CALLS(FROM Chunk TO Chunk, call_type STRING);
+CREATE REL TABLE IF NOT EXISTS IMPORTS(FROM Chunk TO File, import_name STRING);

package/scaffold/.context/rules.yaml

@@ -0,0 +1,25 @@
+rules:
+  - id: rule.source_of_truth
+    description: "Source-of-truth entities must be prioritized in retrieval and final context."
+    priority: 100
+    enforce: true
+
+  - id: rule.deprecated_filter
+    description: "Deprecated entities must be excluded unless explicitly requested."
+    priority: 95
+    enforce: true
+
+  - id: rule.adr_recency
+    description: "Newer ADR supersedes older ADR when both address the same decision."
+    priority: 90
+    enforce: true
+
+  - id: rule.conflict_flag
+    description: "If two active sources conflict, return both and flag a conflict instead of guessing."
+    priority: 90
+    enforce: true
+
+  - id: rule.context_budget
+    description: "Limit runtime context to highest-signal evidence blocks (top_k)."
+    priority: 80
+    enforce: true

package/scaffold/.githooks/_cortex-update-runner.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$REPO_ROOT" ]]; then
+  exit 0
+fi
+
+CONTEXT_SCRIPT="$REPO_ROOT/scripts/context.sh"
+if [[ ! -x "$CONTEXT_SCRIPT" ]]; then
+  exit 0
+fi
+
+PARSER_MODULES_DIR="$REPO_ROOT/scripts/parsers/node_modules"
+
+HOOK_DIR="$REPO_ROOT/.context/hooks"
+LOCK_DIR="$HOOK_DIR/update.lock"
+LAST_RUN_FILE="$HOOK_DIR/last-update.epoch"
+LOG_FILE="$HOOK_DIR/update.log"
+MIN_INTERVAL_SEC="${CORTEX_HOOK_MIN_INTERVAL:-8}"
+
+mkdir -p "$HOOK_DIR"
+
+if [[ ! -d "$PARSER_MODULES_DIR" ]]; then
+  printf "[hook] %s skip update (missing %s, run cortex bootstrap)\n" \
+    "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+    "$PARSER_MODULES_DIR" >> "$LOG_FILE" 2>&1
+  exit 0
+fi
+
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  # Another hook-triggered update is already running.
+  exit 0
+fi
+
+cleanup() {
+  rmdir "$LOCK_DIR" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+now_epoch="$(date +%s)"
+if [[ -f "$LAST_RUN_FILE" ]]; then
+  last_epoch="$(cat "$LAST_RUN_FILE" 2>/dev/null || echo 0)"
+  if [[ "$last_epoch" =~ ^[0-9]+$ ]] && (( now_epoch - last_epoch < MIN_INTERVAL_SEC )); then
+    exit 0
+  fi
+fi
+
+echo "$now_epoch" > "$LAST_RUN_FILE"
+
+{
+  printf "[hook] %s start context update\n" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  if bash "$CONTEXT_SCRIPT" update; then
+    printf "[hook] %s update ok\n" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  else
+    printf "[hook] %s update failed\n" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  fi
+} >> "$LOG_FILE" 2>&1

package/scaffold/.githooks/post-checkout

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Args:
+# 1: previous HEAD
+# 2: new HEAD
+# 3: 1 if branch checkout, 0 if file checkout
+if [[ "${3:-0}" != "1" ]]; then
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$REPO_ROOT" ]]; then
+  exit 0
+fi
+
+RUNNER="$REPO_ROOT/.githooks/_cortex-update-runner.sh"
+if [[ ! -x "$RUNNER" ]]; then
+  exit 0
+fi
+
+nohup bash "$RUNNER" >/dev/null 2>&1 &

package/scaffold/.githooks/post-merge

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$REPO_ROOT" ]]; then
+  exit 0
+fi
+
+RUNNER="$REPO_ROOT/.githooks/_cortex-update-runner.sh"
+if [[ ! -x "$RUNNER" ]]; then
+  exit 0
+fi
+
+nohup bash "$RUNNER" >/dev/null 2>&1 &

package/scaffold/docs/architecture.md

@@ -0,0 +1,22 @@
+# Cortex v1 Architecture
+
+## Goal
+Provide high-signal, repo-local context to coding agents without bloating instruction files.
+
+## Pipeline
+1. Ingestion: source files -> entities + relations
+2. Storage: graph (RyuGraph) + optional vector index
+3. Retrieval: semantic + graph
+4. Policy: rules filter conflicts/deprecated/source-of-truth
+5. Assembly: runtime context package for MCP tool responses
+
+## Runtime Context Order
+1. Task
+2. Hard rules
+3. Evidence blocks (top_k)
+4. Uncertainties
+
+## Guardrails
+- Source-of-truth must be preferred
+- Deprecated content excluded by default
+- Conflicts are flagged, not guessed