ctx-gen-mcp

Code context wiki generator -- MCP Server + OpenCode plugin for navigable, progressive-disclosure code docs with domain grouping, tags, and dependency graph.

What It Does

Generates a navigable Code Wiki for large projects, so AI coding agents can quickly locate and understand any module without reading the entire codebase.

Instead of dumping flat documentation, ctx-gen produces:

• INDEX.md -- single entry point with domain table, tag index, and module list
• Cross-linked wiki pages -- each module has its own .wiki.md with YAML front-matter, summary, dependency links, and detailed content
• Domain grouping -- modules auto-grouped by directory structure
• Tag-based lookup -- find modules by language, architecture level, tech feature
• Dependency graph -- shallow #include/import analysis with cross-links

Progressive Disclosure

The wiki is designed so AI agents read the minimum to locate what they need:

1. INDEX.md (~50-100 lines) -- scan domains and tags
2. lookup MCP tool -- find modules by keyword without reading the INDEX
3. Module wiki page -- full context for one module with cross-links to related modules
4. Follow links -- Depends: / Used by: links for impact analysis

One-Click Install

# 1. Install the pip package
pip install ctx-gen-mcp

# 2. Run one-click setup (installs skill + agent + MCP config)
ctx-gen-setup

That's it. OpenCode will now have:

• A ctx-gen skill (loadable via /ctx-gen)
• A ctx-gen agent (switchable in agent panel)
• MCP server config in opencode.json
• AGENTS.md in your project root

Usage

In OpenCode (recommended)

1. Open your project in OpenCode
2. Say: "use the ctx-gen skill to generate context wiki"
3. Or switch to the ctx-gen agent in the agent panel
4. The agent will: scan -> generate per-module JSON -> validate -> assemble wiki

MCP Tools (any MCP-compatible agent)

The package exposes 4 deterministic MCP tools:

Tool	What it does
scan_skeleton	Scan repo -> skeleton with domains, tags, dependency graph
lookup	Find modules by tag/domain/keyword (no need to read full INDEX)
validate_coverage	Check all modules have context, detect stale ones
assemble_docs	Build wiki INDEX.md + cross-linked .wiki.md pages

CLI

# Run MCP server directly (for testing)
ctx-gen-server

# Or:
python -m ctx_gen_mcp.server

# Re-run setup (e.g. after moving project)
ctx-gen-setup --project-dir /path/to/project

# Install globally (all projects)
ctx-gen-setup --global

# Uninstall
ctx-gen-setup --uninstall

Output

After running, you'll have:

.ctx-cache/
  skeleton.json             # repo structure with domains/tags/deps (deterministic)
  ctx/
    <module_id>.json       # per-module structured context
docs/
  wiki/
    INDEX.md               # single entry point
    domains/
      <domain>/
        <module>.wiki.md   # cross-linked per-module wiki page

Add these to .gitignore:

.ctx-cache/
docs/wiki/

Architecture

Core Insight: Separate Deterministic from LLM Operations

Operation	Who does it	Why
Repo scanning + domain grouping	scan_skeleton (deterministic)	Glob + regex never hallucinates
Module lookup by tag/keyword	lookup (deterministic)	String matching is exact
Per-module description	LLM (via Agent)	Needs semantic understanding
Coverage validation	validate_coverage (deterministic)	Hash comparison is exact
Wiki assembly	assemble_docs (deterministic)	Template + cross-link generation

Domain Grouping (Hybrid Strategy)

1. Directory-based first: src/engine/ -> domain "engine"
2. If a domain has >10 modules, flagged for potential LLM subdivision
3. Domains are reflected in the output directory structure

Tag Inference (Automatic)

Tags are inferred from file names, directory names, and shallow content analysis:

Dimension	Examples	Detection Method
Language	cpp, python, c	File extension statistics
Architecture	kernel-mode, user-mode, shared-lib	Filename + content keywords
Tech feature	driver, crypto, network, async, ipc	Filename + content keywords
Build target	static-lib, shared-lib, exe	Build system analysis

Dependency Detection (Shallow)

Only direct #include, import, require statements are analyzed. This covers ~80% of real dependencies with zero parser overhead.

Requirements

• Python >= 3.10
• OpenCode >= 1.0 (for skill/agent support)
• Or any MCP-compatible agent (Claude Code, etc.)

License

MIT