Generate-documentation-MCP

MCP server for Claude Code that turns a Git repository's changes — uncommitted, a single commit, or a whole branch — into a structured Markdown documentation skeleton — diffs, file list and placeholders — ready for Claude Code to fill in with the actual analysis.

This is a standalone product, not an evolution of Generate-documentation-IA. That project's gendoc shell script was used only as a reference for the skeleton format; this repo does not reuse its code.

Design

• No AI API calls. All language understanding ("ignore CSS files", "document this in Portuguese") happens in Claude Code, which translates the request into structured parameters. The MCP server only executes them: reads Git diffs, applies include/exclude filters, renders a template, and writes the file.
• core/ owns all logic. cli/ and mcp_server/ are thin adapters that call core.generator.generate_documentation() and format its result — neither contains business rules.
• Skeleton, not final prose. The generated Markdown mirrors the original script's workflow: diffs are embedded with [To be filled by AI] placeholders. After calling the tool, Claude Code edits the output file directly to fill in the analysis.

core/          diff collection, filtering, template rendering, file writing
cli/           argparse wrapper around core, for local/manual use
mcp_server/    FastMCP server exposing the generate_documentation tool
templates/     Jinja2 skeleton templates (default_en.md.j2, default_pt.md.j2)
tests/         pytest suite (uses real throwaway Git repos via subprocess)

All Git commands live in core/git_diff.py — nothing else in the project shells out to git. It exposes one function per diff source:

• get_working_tree_diff(project_path) — staged + unstaged uncommitted changes
• get_commit_diff(project_path, commit_hash) — a single commit (defaults to HEAD)
• get_branch_diff(project_path, base_branch) — current branch vs base_branch...HEAD

All three return the same list[ChangedFile] shape, so core/generator.py and the Markdown template never know which mode produced the diff — only mode picks which function runs; everything downstream (filtering, rendering, writing) is identical for every mode.

Note: the MCP-facing package is named mcp_server/, not mcp/, because mcp is the name of the official MCP SDK this project depends on — a top-level mcp/ package in this repo would shadow it on import.

The generate_documentation tool

Parameters:

Name	Type	Default	Meaning
project_path	string	server cwd	Git repository to analyze
include	string[]	none (= all)	Glob patterns; only matching changed files are kept
exclude	string[]	none	Glob patterns to drop, applied after include
output_file	string	documentation.md	Output path, relative to project_path unless absolute
language	"en"|"pt"	"en"	Skeleton language
title	string	language default	Document title
template	string	"default"	Template name, resolved as templates/{template}_{language}.md.j2
mode	"working_tree"|"commit"|"branch"	"working_tree"	Diff source
commit_hash	string | null	null (= HEAD)	Commit to document, used when mode="commit"
base_branch	string	"origin/main"	Base branch to diff against, used when mode="branch" (base_branch...HEAD)

Calling the tool with no arguments beyond project_path keeps documenting uncommitted changes exactly as before — mode defaults to "working_tree".

Returns:

{
  "success": true,
  "output_file": "/path/to/documentation.md",
  "files_processed": 12,
  "files_ignored": 3
}

On failure (success: false), a error field explains what went wrong (not a Git repo, unknown template, unwritable path).

Diff scope matches the original script: staged + unstaged uncommitted changes, staged diff taking priority for files with both.

Installation

Requires Python 3.10+.

git clone https://github.com/Paulosouzx/Generate-documentation-MCP.git
cd Generate-documentation-MCP
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

This installs the gendoc-mcp (CLI) and gendoc-mcp-server (MCP server) console scripts into .venv/bin/.

Registering with Claude Code

Register it once, at user scope, so it's available in every project:

claude mcp add --scope user --transport stdio gendoc -- \
  /absolute/path/to/Generate-documentation-MCP/.venv/bin/gendoc-mcp-server

Verify it's registered:

claude mcp list

or run /mcp inside a Claude Code session.

Using it

Inside any Git repository, in Claude Code, describe what you want in plain language — Claude Code translates it into tool parameters, the server writes documentation.md with the diffs and placeholders, and Claude Code then edits that file in place to fill in the actual analysis.

Document local (uncommitted) changes

"Document the changes on this branch, ignoring CSS files, in Portuguese."

{"exclude": ["*.css"], "language": "pt"}

(mode omitted — defaults to "working_tree".)

Document a specific commit

"Document what changed in commit a1b2c3d."

{"mode": "commit", "commit_hash": "a1b2c3d"}

"Document the last commit."

{"mode": "commit"}

(commit_hash omitted — defaults to HEAD.)

Document a whole branch

"Document everything this branch adds compared to origin/develop."

{"mode": "branch", "base_branch": "origin/develop"}

(base_branch omitted — defaults to "origin/main".)

Development

pip install -e ".[dev]"
pytest

CLI usage (no Claude Code needed), useful for manual testing:

# Uncommitted changes (default mode)
gendoc-mcp
gendoc-mcp --mode working_tree --exclude "*.css" --language pt

# A specific commit (defaults to HEAD if --commit omitted)
gendoc-mcp --mode commit --commit a1b2c3d

# Current branch vs a base branch (defaults to origin/main)
gendoc-mcp --mode branch --base origin/develop

Adding a new tool

Add the core function in core/, then expose it with a new @mcp.tool() function in mcp_server/server.py that calls it — no logic in the server itself. Add a matching CLI subcommand in cli/ if useful for manual/local use.