README.md

metadata

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:

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:

   git clone <repository_url>
   cd <repository_name>
   

2. Create a virtual environment (recommended):

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

3. Install the dependencies:

   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.

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:

   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.