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

Related MCP server: mcp-codemap

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:

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

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:

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