Repo Knowledge
Repo knowledge system — relational catalog with full-text search, audit evidence, and MCP access
Ask AI about Repo Knowledge
Powered by Claude · Grounded in docs
I know everything about Repo Knowledge. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
日本語 | 中文 | Español | हिन्दी | Italiano | Português (BR)
Local-first repo knowledge system built on SQLite and FTS5. Catalogs repositories with structured metadata, thesis notes, architecture docs, audit evidence, and inter-repo relationships — then exposes everything through a CLI and MCP server for AI-integrated workflows.
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+
ghCLI (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
| Command | Description |
|---|---|
rk init | Initialize config, database, and seed audit controls |
rk sync | Full sync: GitHub orgs + local repos + FTS index |
rk scan <path> | Scan a single local repo directory |
rk show <slug> | Show full repo knowledge with audit posture |
rk list | List all repos (filterable by status, language, shape) |
rk find <query> | Full-text search across all indexed content |
rk related <slug> | Show repos related to a given repo |
rk note <slug> | Add a typed note (thesis, architecture, warning, etc.) with --type and --content (optional --title) |
rk relate <from> <type> <to> | Record a relationship between repos (optional --note) |
rk stats | Show database statistics |
rk reindex | Rebuild the FTS index |
rk sync-dogfood | Sync dogfood evidence from dogfood-lab/testing-os into repo facts |
Audit Commands
| Command | Description |
|---|---|
rk audit seed-controls | Seed/update the 80-control canonical catalog |
rk audit import <dir> | Import audit results from JSON contract files |
rk audit posture [slug] | Show audit posture for one repo or full portfolio |
rk audit findings | List open findings across the portfolio |
rk audit controls | List canonical controls by domain |
rk audit unaudited | List repos with no audit runs |
rk audit failing <domain> | List repos failing a specific audit domain |
Games Commands
| Command | Description |
|---|---|
rk games score <worklist> | Score a REMEDIATION-WORKLIST.md and show leaderboard |
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:
| Domain | Controls |
|---|---|
| inventory | Repo metadata, ownership, classification |
| code_quality | Linting, formatting, complexity |
| security_sast | Static analysis, injection, auth |
| dependencies_sca | Vulnerability scanning, currency |
| licenses | License compliance, compatibility |
| secrets | Secret detection, rotation |
| config_iac | Infrastructure-as-code hygiene |
| containers | Image security, scanning |
| runtime | Error handling, resilience |
| performance | Profiling, optimization |
| observability | Logging, tracing, metrics |
| testing | Coverage, types, CI integration |
| cicd | Pipeline security, gates |
| deployment | Release process, rollback |
| backup_dr | Backup plans, recovery |
| monitoring | Alerting, uptime |
| compliance_privacy | Data handling, GDPR |
| supply_chain | SBOM, provenance |
| integrations | API contracts, versioning |
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:
- Audit Pass — Each agent claims repos from the worklist, runs the 80-control audit, and submits structured results
- Enrichment Pass — Agents add thesis, architecture notes, and relationship mappings
- 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
Built by MCP Tool Shop
