{
  "markdown": "\n> [!NOTE]\n> **Phase 9 (Python-Only Release)** is now supported in this server (v0.1.0)!\n>\n> The analyzer generates **Python-focused onboarding**. Non-Python repos will see a neutral \"Python tooling not detected\" message.\n> Node.js/TypeScript commands are not generated yet (deferred to Phase 10).\n\n# mcp-repo-onboarding — MCP Server for Static Analysis & Onboarding\n\nA professional MCP server for analyzing local Python repositories and generating practical `ONBOARDING.md`. It detects environment configuration, dependencies, scripts, and frameworks with **deterministic, static analysis** (no execution, no network).\n\n---\n\n## ✨ Features\n\n- **📊 Repo Structure Analysis**: Analyzes local Python repository layout and categorizes files (docs, configs, dependencies).\n- **🧰 Dependency Detection**: Detects Python environment files (`requirements.txt`, `pyproject.toml`, `setup.py`, etc.).\n- **⚙️ Command Detection**: Extracts developer and test commands from `Makefile`, `tox.ini`, `shell scripts`, and more.\n- **🔍 Framework Detection**: Detects popular Python frameworks (Django, Flask, FastAPI, Streamlit, Gradio) from `pyproject.toml` and `requirements.txt`.\n- **📝 ONBOARDING.md Generation**: Generates validator-compliant onboarding documents with consistent heading order.\n- **📜 Changelog**: Track project history in [CHANGELOG.md](CHANGELOG.md).\n- **🛡️ Safe & Deterministic**: Uses static file I/O only (no subprocess, no network, no command execution).\n- **🔧 Other Tooling Reporting**: Reports secondary tooling (Node.js, Docker, Go, Rust) neutrally via evidence files (Phase 9).\n\n---\n\n## 📋 Prerequisites\n\n1. **Python 3.11+** installed.\n2. **[uv](https://github.com/astral-sh/uv)** (recommended for faster installation).\n3. **Gemini CLI** (or any LLM runtime that supports MCP servers).\n\n---\n\n## 🚀 Installation\n\n### 1. Install Server Locally\n\nInstall the server locally using `uv` (recommended):\n\n```bash\ngit clone https://github.com/rogermt/mcp-repo-onboarding.git\ncd mcp-repo-onboarding\nuv sync\n```\n\n### 2. Run Server\n\nRun the server in standalone mode:\n\n```bash\nuv run mcp-repo-onboarding\n```\n\n### 3. Install as Gemini CLI Extension (Recommended)\n\nThis server is designed to be installed as an extension in [Gemini CLI](https://github.com/google-gemini/gemini-cli).\n\n```bash\n# From GitHub\ngemini extensions install https://github.com/rogermt/mcp-repo-onboarding\n\n# From local path\ngemini extensions install /path/to/mcp-repo-onboarding\n```\n\n### 4. Activate\n\nRestart the Gemini CLI. The following MCP tools will be available:\n\n- `/analyze_repo` — Analyze local repository and return structured JSON.\n- `/write_onboarding` — Write (or overwrite) `ONBOARDING.md` to the repo root.\n- `/read_onboarding` — Read existing `ONBOARDING.md` content.\n- `/get_run_and_test_commands` — Get simplified run/test command suggestions.\n\n---\n\n## 💡 Usage\n\nThe server provides MCP tools for analyzing repositories and managing onboarding documents.\n\n### 🎯 Specific Tools (Recommended)\n\n**Analyze Repository:**\n\n```bash\n# Analyze current directory (default)\n/analyze_repo\n\n# Analyze specific path\n/analyze_repo path/to/repo\n```\n\n**Generate ONBOARDING.md:**\n\n```bash\n# Write to repo root (default, uses blueprint)\n/write_onboarding\n\n# Append to existing file\n/write_onboarding mode=\"append\"\n\n# Overwrite existing file\n/write_onboarding mode=\"overwrite\"\n```\n\n**Read ONBOARDING.md:**\n\n```bash\n# Read from repo root\n/read_onboarding\n\n# Read specific path\n/read_onboarding path/to/ONBOARDING.md\n```\n\n**Get Run & Test Commands:**\n\n```bash\n# Get suggestions\n/get_run_and_test_commands\n```\n\n### 🔧 Advanced Options (Environment Variables)\n\nYou can customize behavior by setting environment variables:\n\n- **`MCP_REPO_ONBOARDING_MAX_FILES`** (default: `5000`)\n  - Maximum number of files to scan in the repo.\n\n- **`MCP_REPO_ONBOARDING_PYTHON_DETECTED`** (calculated)\n  - Indicates whether Python was detected (used internally for scope messaging).\n\n---\n\n## 🎨 Advanced Analysis Features\n\n### Framework Detection\n\nThe analyzer detects Python frameworks from `pyproject.toml` and `requirements.txt`.\n\n**Supported Frameworks:**\n- Django (Classifiers + Poetry deps)\n- Wagtail (Classifiers)\n- Flask (Poetry deps)\n- FastAPI (Poetry deps)\n- Streamlit (Requirements deps)\n- Gradio (Requirements deps)\n\n**Note:** Framework detection is evidence-only and does not infer commands.\n\n### Notebook Detection & Capping\n\nThe analyzer detects Jupyter notebook directories.\n\n- **Truncation:** The list of notebook directories in `ONBOARDING.md` is capped to `20` entries to prevent massive lists (e.g., in monorepos).\n- **Note:** If truncated, a message like `\"* notebooks list truncated to 20 entries (total=215)\"` is added to Analyzer notes.\n\n### \"Other Tooling Detected\" (Phase 9)\n\nSecondary tooling (e.g., Node.js, Docker, Go) is reported neutrally in the `Other tooling detected` section.\n\n- **Evidence Files:** Lists explicit files (e.g., `.nvmrc`, `package.json`).\n- **No Commands:** No `npm`, `yarn`, `pnpm`, or `docker` commands are suggested.\n- **Sorting & Truncation:** Evidence lists are sorted alphabetically and capped to 3 files with a deterministic note.\n\n---\n\n## 🏗️ Architecture\n\n### Analysis Pipeline\n\n1. **File Scanning**: Scans repo tree (respects `.gitignore`, safety ignores).\n2. **Categorization**: Sorts files into docs, configs, deps, scripts.\n3. **Prioritization**: Ranks files by importance (root, standards, keywords).\n4. **Extraction**:\n   - **Scripts**: `Makefile`, `tox.ini`, `shell` scripts.\n   - **Frameworks**: `pyproject.toml`, `requirements.txt`.\n   - **Other Tooling**: `.nvmrc`, `package.json`, lockfiles.\n5. **Bluepring Generation**: Compiles sections from a registry (`onboarding_blueprint_engine`).\n6. **Validation**: Output is checked against validator rules (V1-V3).\n\n### Registry Pattern\n\nThe blueprint engine uses a **registry pattern** (Strategy Pattern) for detectors.\n\n- **Detectors:** `PyprojectClassifierDetector`, `PoetryDependencyDetector`, `RequirementsDetector`.\n- **Extensible:** Add new detectors by registering them in `DETECTORS`.\n\n---\n\n## 📁 File Management\n\n### Input/Output Locations\n\n- **Repo Root:** The target repository path (default: `.`).\n- **ONBOARDING.md:** Written to the root of the target repository.\n- **Analysis Cache:** No persistent cache; analysis is performed on demand.\n\n### Safety Ignores\n\nThe scanner ignores specific paths to prevent noise and ensure determinism:\n\n- `tests/fixtures/`\n- `test/fixtures/`\n- `.git/`, `.venv/`, `__pycache__/`\n- `node_modules/`, `site-packages/`\n\n---\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **\"No Python detected\" message appears:**\n   - **Cause:** The repo has no explicit Python evidence files (`pyproject.toml`, `setup.py`, `requirements.txt`) or `.py` files.\n   - **Fix:** This is expected for non-Python repos in Phase 9. The onboarding will still be generated but will state Python-only scope.\n\n2. **\"No explicit commands detected\" in sections:**\n   - **Cause:** No Makefile, `tox.ini`, or shell scripts found with recognizable targets.\n   - **Fix:** Add a `Makefile` or `tox.ini` with standard targets (`test`, `install`, `lint`).\n\n3. **\"No description provided by analyzer\" for scripts:**\n   - **Cause:** Script has no safe header comment.\n   - **Fix:** Add a safe header comment (e.g., `# Run the test suite`) to the top of the script.\n\n4. **ONBOARDING.md validation fails:**\n   - **Cause:** Generated document does not match validator rules (missing required headings, wrong bullets).\n   - **Fix:** This should not happen with Phase 9. If it does, run `scripts/validate_onboarding.py` locally to debug.\n\n### Debug Mode\n\nThe server logs detailed warnings to the console:\n\n```bash\n# Run with debug output\nuv run mcp-repo-onboarding\n```\n\n---\n\n## 📊 Technical Details\n\n### MCP Server Protocol\n\n- **Protocol:** JSON-RPC over stdio\n- **SDK:** `mcp[cli]>=1.25.0`\n- **Tools:** `analyze_repo`, `write_onboarding`, `read_onboarding`, `get_run_and_test_commands`\n\n### Analysis Core\n\n- **Language:** Python 3.11+\n- **Dependencies:** `packaging`, `pathspec`, `pydantic`, `tomllib`\n- **File I/O:** Standard library (`pathlib`, `os`)\n\n### Schema (`RepoAnalysis`)\n\n- `repoPath`: Repository root path.\n- `python`: Python env info (versions, package managers, deps).\n- `scripts`: Grouped scripts (dev, test, lint, format, install).\n- `frameworks`: List of detected frameworks.\n- `configurationFiles`: Config files (Makefile, workflows, etc.).\n- `docs`: Documentation files.\n- `notebooks`: Notebook directories.\n- `otherTooling`: Secondary tooling (Node.js, Docker, etc.).\n- `notes`: Analyzer notes (truncations, etc.).\n\n### Blueprint Engine\n\n- **Module:** `onboarding_blueprint_engine`\n- **Registry:** `registry.py` (list of `SectionSpec`).\n- **Render Mode:** Verbatim (bullet list format).\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository.\n2. Create a feature branch.\n3. Make your changes (ensure tests pass).\n4. Run `uv run pytest` and `uv run mypy`.\n5. Submit a pull request.\n\n---\n\n## 📄 Legal\n\n- **License:** [Apache License 2.0](LICENSE)\n- **Security:** [Security Policy](SECURITY.md)\n",
  "bytes": 9071,
  "sha": "30f681be3235bafeebc76be0989c9e27a06cae950eea64dd5e208df3a3cae48b",
  "repo_slug": "rogermt/mcp-repo-onboarding",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_rogermt_mcp_repo_onboarding_392b6a6a/readme"
}