---
title: Agents MCP Hackathon
emoji: 🐠
colorFrom: indigo
colorTo: red
sdk: gradio
sdk_version: 5.33.1
app_file: app.py
pinned: false
license: mit
short_description: Automatic documentation generator for GitHub or zipped repos
tags:
    - mcp-server-track
    - gradio-app
    - hackathon
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# 🤖 AutoDocs – MCP Server for Automatic Code Documentation

Automatic documentation generator for GitHub or zipped repositories.

**AutoDocs** is a Gradio-based application that serves as an **MCP Server (Track 1)** for the Agents & MCP Hackathon.  
It automatically generates documentation, README files, and requirements.txt for any Python code repository provided via GitHub URL or ZIP file.

---

## 🚀 Features

- 📦 Upload and process any ZIP file of a code repo.
- 🌐 Clone and process any GitHub repository.
- 📄 Auto-generate:
  - Docstrings (Google style)
  - Typings
  - Inline code comments
  - `requirements.txt`
  - `README.md` + `index.md`
- 🧠 Integrated AI agent to ask questions about the code.

---

## 🛠️ MCP Server Information

✅ This Space is an **MCP Server (Track 1)** compliant with the MCP protocol.

MCP Metadata (`.well-known/mcp.yaml`)

## 💻 Usage (as MCP Client)

This server can be queried via Claude Desktop, Cursor, or Tiny Agents MCP clients.

Example with Tiny Agents: 

```bash
tiny-agents call --url https://huggingface.co/spaces/your-space-name
```

## Project Description

AutoDocs is a tool designed to automatically generate documentation, requirements files, and README files for Python projects. It leverages generative AI to add helpful comments and type annotations to your code, making it easier to understand and maintain.  It can process a local repository, a GitHub repository via URL, or a zipped source code directory.

## Installation

1.  **Clone the repository:**

    ```bash
    git clone <repository_url>
    cd <repository_name>
    ```

2.  **Create a virtual environment (recommended):**

    ```bash
    python3 -m venv venv
    source venv/bin/activate  # On Linux/macOS
    venv\Scripts\activate  # On Windows
    ```

3.  **Install the dependencies:**

    ```bash
    pip install -r requirements.txt
    ```

4.  **Set up the environment variables:**

    *   Create a `.env` file in the root directory of the project.
    *   Add your Google Gemini API key to the `.env` file:

        ```
        GOOGLE_API_KEY=<your_google_api_key>
        ```

        **Note:**  You will need a Google Gemini API key to use the documentation generation features. You can obtain one from the Google AI Studio.

## Usage

### Using the `app.py` module:

The `app.py` module contains the core logic for processing a repository and generating documentation.

```python
import gradio as gr
import os
import shutil
import tempfile
import zipfile
import subprocess
import uuid

from doc_generator import generate_documented_code, generate_requirements_txt
from readme_generator import generate_readme_from_zip


def process_repo(repo_path: str, zip_output_name: str = "AutoDocs") -> str:
    """Processes a repository to generate documentation, requirements, and a README.

    Args:
        repo_path: The path to the repository.
        zip_output_name: The name of the output zip file (default: "AutoDocs").

    Returns:
        The path to the generated zip file.
    """
    with tempfile.TemporaryDirectory() as temp_output_dir:
        # Iterate through all Python files in the repository and generate documented code.
        for root, _, files in os.walk(repo_path):
            for file in files:
                if file.endswith(".py"):
                    file_path = os.path.join(root, file)
                    generate_documented_code(file_path, file_path)


# Example Usage (not executable directly from this file, intended for integration):
# repo_path = "/path/to/your/repository"
# output_zip = process_repo(repo_path)
# print(f"Generated documentation zip file: {output_zip}")
```

### Using the FastAPI server (`mcp_server.py`):

The `mcp_server.py` module provides a FastAPI server with endpoints for generating documentation from a GitHub URL or a zip file upload.

1.  **Run the FastAPI server:**

    ```bash
    uvicorn mcp_server:app --reload
    ```

2.  **Access the endpoints:**

    *   **Generate documentation from a GitHub URL:**

        ```
        POST /generate_docs
        Content-Type: multipart/form-data

        github_url=<your_github_url>
        ```

    *   **Generate documentation from a zip file upload:**

        ```
        POST /generate_docs
        Content-Type: multipart/form-data

        zip_file=@<path_to_your_zip_file>
        ```

    *   **MCP Manifest (/.well-known/mcp.yaml):**

        ```
        GET /.well-known/mcp.yaml
        ```
        This endpoint serves the MCP manifest file.

## Features

*   **Automated Documentation Generation:** Uses generative AI to add comments and type annotations to Python code.
*   **Requirements File Generation:**  Automatically creates a `requirements.txt` file listing the project dependencies.
*   **README Generation:**  Generates a basic README file based on the project structure and code content.
*   **GitHub URL Processing:**  Can process repositories directly from GitHub URLs.
*   **Zip File Upload:**  Supports uploading zip files of source code for documentation generation.
*   **MCP Manifest Serving:** Includes an endpoint to serve an MCP (Meta Control Protocol) manifest.

## Authors

Aguet Theau, Azdad Bilal.

## License

MIT License.