Repo Knowledge

Why

Package registries and GitHub APIs tell you what a repo is. They don't tell you what it's for, how it relates to your other repos, what its architectural thesis is, or whether it passed your last security audit. repo-knowledge fills that gap: a single local database that holds thesis, architecture, audit evidence, relationships, and full-text search across all of it.

Install

npm install -g @mcptoolshop/repo-knowledge

Requirements:

• Node.js 20+
• gh CLI (authenticated) for GitHub sync
• C/C++ build tools for better-sqlite3, or prebuild binaries will be used automatically on supported platforms

Security Model

Data touched: local SQLite database, GitHub API metadata via gh CLI (repo names, descriptions, topics, stars — no source code content).

Data NOT touched: no source code is read from GitHub, no credentials are stored, no data is sent to external services.

Permissions: requires gh CLI authenticated for GitHub sync; all data stays local.

No telemetry, no analytics, no phone-home.

Quick Start

# Initialize workspace — creates config, database, seeds audit controls
rk init

# Sync repos from your GitHub org
rk sync --owners my-org

# Include forked repos
rk sync --owners my-org --forks

# Inspect a specific repo
rk show my-org/my-repo

# Search across everything
rk find "authentication middleware"

# Seed the 80-control audit framework
rk audit seed-controls

CLI Reference

Core Commands

Audit Commands

Games Commands

MCP Server

The MCP server exposes 19 tools for AI-integrated workflows. Add it to your MCP client config:

Claude Code (project-scoped .claude.json):

{
  "mcpServers": {
    "repo-knowledge": {
      "command": "rk",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "repo-knowledge": {
      "command": "node",
      "args": ["node_modules/@mcptoolshop/repo-knowledge/dist/mcp/server.js"]
    }
  }
}

The server reads rk.config.json from the working directory at startup. Make sure rk.config.json exists in the directory where the server runs.

MCP Tools

get_repo find_repos search_repos related_repos repos_by_stack repos_needing_work repo_summary add_repo_note add_relationship knowledge_stats sync_repos sync_dogfood audit_posture audit_portfolio audit_findings audit_detail audit_submit audit_controls_list audit_unaudited

Audit Framework

The audit system covers 19 domains with 80 controls:

Each audit run produces structured evidence: control results (pass/fail/warn/not_applicable), findings with severity and remediation, and aggregate metrics. Posture is derived automatically: healthy, needs_attention, or critical.

Multi-Agent Orchestration: The Claude Games

repo-knowledge includes templates for parallel multi-Claude operations across large portfolios. The Claude Games coordinate multiple AI agents through a shared worklist:

1. Audit Pass — Each agent claims repos from the worklist, runs the 80-control audit, and submits structured results
2. Enrichment Pass — Agents add thesis, architecture notes, and relationship mappings
3. Remediation Pass — Agents fix findings using a scored 8-step workflow

See templates/claude-games/ for the full playbook.

Data Model

repos
 +-- tech (language, framework, shape, runtime)
 +-- notes (thesis, architecture, warning, convention, ...)
 +-- docs (README, CHANGELOG, indexed content)
 +-- facts (dependencies, config keys, endpoints)
 +-- relationships (depends_on, related_to, supersedes, ...)
 +-- audit_runs
      +-- audit_control_results (per-control pass/fail)
      +-- audit_findings (title, severity, remediation)
      +-- audit_metrics (pass_rate, coverage, counts)

All data lives in a single SQLite database with FTS5 full-text search across docs, notes, and repo descriptions.

Configuration

Create rk.config.json in your workspace root (or run rk init):

{
  "owners": ["your-github-org"],
  "localDirs": ["."],
  "dbPath": "data/knowledge.db",
  "artifactsRoot": "data/artifacts"
}

All settings come from rk.config.json (created by rk init). The MCP server also reads config from the working directory.

License

MIT

Built by MCP Tool Shop