feat: add MCP (Model Context Protocol) server support

- Add MCP server implementation with stdio transport
- Integrate MCP server option in CLI with --mcp-server flag
- Add ingest_repository tool for MCP clients
- Remove HTTP transport, keeping only stdio for simplicity
- Add MCP dependencies and optional installation group
- Include comprehensive documentation and client examples
- Support GitHub token authentication through MCP

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

docs/MCP_USAGE.md

@@ -0,0 +1,136 @@
+# Gitingest MCP Server
+
+Gitingest includes an MCP (Model Context Protocol) server that allows LLMs to directly access repository analysis capabilities through the MCP protocol.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a standardized protocol that enables language models to interact with external tools and resources in a structured manner. It facilitates the integration of specialized capabilities into LLM workflows.
+
+## Installation
+
+To use the MCP server, install Gitingest with MCP dependencies:
+
+```bash
+pip install gitingest[mcp]
+```
+
+## Starting the MCP Server
+
+### Stdio Transport (Default)
+
+```bash
+gitingest --mcp-server
+```
+
+The MCP server uses stdio for communication by default, making it compatible with all MCP clients.
+
+
+## Available Tools
+
+### `ingest_repository`
+
+Ingests a Git repository or local directory and returns a structured digest.
+
+**Parameters:**
+- `source` (required): Git repository URL or local directory path
+- `max_file_size` (optional): Maximum file size in bytes (default: 10485760)
+- `include_patterns` (optional): Shell patterns to include files
+- `exclude_patterns` (optional): Shell patterns to exclude files
+- `branch` (optional): Git branch to clone and ingest
+- `include_gitignored` (optional): Include files ignored by .gitignore (default: false)
+- `include_submodules` (optional): Include Git submodules (default: false)
+- `token` (optional): GitHub personal access token for private repositories
+
+**Usage example:**
+```json
+{
+  "source": "https://github.com/coderamp-labs/gitingest",
+  "max_file_size": 1048576,
+  "include_patterns": ["*.py", "*.md"],
+  "exclude_patterns": ["tests/*"]
+}
+```
+
+## MCP Client Configuration
+
+### Stdio Transport Configuration
+
+Create a configuration file for your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "gitingest": {
+      "command": "gitingest",
+      "args": ["--mcp-server"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+
+### Environment Variables
+
+- `GITHUB_TOKEN`: GitHub personal access token for private repositories
+
+## Integration Examples
+
+### Python Client Examples
+
+See the following examples for how to use the Gitingest MCP server:
+
+- **`examples/mcp_client_example.py`** - Stdio transport example
+- **`examples/start_mcp_server.py`** - Startup script for stdio transport
+
+### Integration with Claude Desktop
+
+1. Install Gitingest with MCP dependencies
+2. Create an MCP configuration file in your Claude configuration directory
+3. Restart Claude Desktop
+4. Use Gitingest tools in your conversations
+
+### Integration with Other MCP Clients
+
+The Gitingest MCP server is compatible with all MCP-compliant clients. Consult your MCP client's documentation for specific integration instructions.
+
+## Output Format
+
+The MCP server returns structured content that includes:
+
+1. **Summary**: General information about the repository
+2. **File Structure**: Tree structure of files and directories
+3. **Content**: Code file content with LLM-optimized formatting
+
+## Error Handling
+
+The MCP server handles errors gracefully and returns informative error messages. Common errors include:
+
+- Private repositories without authentication token
+- Invalid repository URLs
+- Network issues during cloning
+- Files that are too large
+
+## Limitations
+
+- The MCP server does not maintain a cache of ingested repositories (future feature)
+- Persistent resources are not yet implemented
+- The server uses stdio transport for MCP communication
+
+## Development
+
+To contribute to the MCP server:
+
+1. Consult the MCP specification: https://modelcontextprotocol.io/
+2. Tests are located in `tests/test_mcp_server.py`
+3. The client example is located in `examples/mcp_client_example.py`
+
+## Support
+
+For help with the MCP server:
+
+- Consult the official MCP documentation
+- Open an issue on GitHub
+- Join the Discord community

examples/mcp-config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "gitingest": {
+      "command": "gitingest",
+      "args": ["--mcp-server"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}

examples/mcp_client_example.py

@@ -0,0 +1,25 @@
+import asyncio
+from mcp.client.session import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+
+async def main():
+    async with stdio_client(
+        StdioServerParameters(command="gitingest", args=["--mcp-server"])
+    ) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            # List available tools
+            tools = await session.list_tools()
+            print("🛠️  Outils disponibles:")
+            for tool in tools.tools:
+                print(f"  - {tool.name}: {tool.description}")
+
+            # Call the ingest_repository tool
+            print("\n📞 Appel de l'outil ingest_repository...")
+            result = await session.call_tool("ingest_repository", {"source": "https://github.com/coderamp-labs/gitingest"})
+            print(result)
+
+
+asyncio.run(main())

examples/start_mcp_server.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""
+Startup script for the Gitingest MCP server.
+
+This script starts the MCP server with stdio transport.
+
+Usage:
+    python examples/start_mcp_server.py
+"""
+
+import sys
+import asyncio
+from pathlib import Path
+
+# Add the src directory to the Python path
+src_path = Path(__file__).parent.parent / "src"
+sys.path.insert(0, str(src_path))
+
+from gitingest.mcp_server import start_mcp_server
+
+
+async def main_wrapper():
+    """Start the MCP server with stdio transport."""
+    print("Starting Gitingest MCP Server")
+    print("   Transport: stdio")
+    print("   Mode: stdio (for MCP clients that support stdio transport)")
+    
+    print("\nServer Configuration:")
+    print("   - Repository analysis and text digest generation")
+    print("   - Token counting and file structure analysis")
+    print("   - Support for both local directories and Git repositories")
+    print()
+    
+    try:
+        await start_mcp_server()
+    except KeyboardInterrupt:
+        print("\nServer stopped by user")
+    except Exception as e:
+        print(f"\nError starting server: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main_wrapper())

pyproject.toml

@@ -53,6 +53,11 @@ server = [
     "uvicorn>=0.11.7",  # Minimum safe release (https://osv.dev/vulnerability/PYSEC-2020-150)
 ]
 
+mcp = [
+    "mcp>=1.0.0",  # Model Context Protocol
+    "pydantic>=2.0.0",
+]
+
 [project.scripts]
 gitingest = "gitingest.__main__:main"
 
@@ -131,3 +136,7 @@ asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 python_classes = "Test*"
 python_functions = "test_*"
+addopts = "--strict-markers"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]

src/gitingest/__main__.py

@@ -29,6 +29,7 @@ class _CLIArgs(TypedDict):
     include_submodules: bool
     token: str | None
     output: str | None
+    mcp_server: bool
 
 
 @click.command()
@@ -76,6 +77,12 @@ class _CLIArgs(TypedDict):
     default=None,
     help="Output file path (default: digest.txt in current directory). Use '-' for stdout.",
 )
+@click.option(
+    "--mcp-server",
+    is_flag=True,
+    default=False,
+    help="Start the MCP (Model Context Protocol) server for LLM integration",
+)
 def main(**cli_kwargs: Unpack[_CLIArgs]) -> None:
     """Run the CLI entry point to analyze a repo / directory and dump its contents.
 
@@ -99,6 +106,9 @@ def main(**cli_kwargs: Unpack[_CLIArgs]) -> None:
         $ gitingest -o -
         $ gitingest https://github.com/user/repo --output -
 
+    MCP server mode:
+        $ gitingest --mcp-server
+
     With filtering:
         $ gitingest -i "*.py" -e "*.log"
         $ gitingest --include-pattern "*.js" --exclude-pattern "node_modules/*"
@@ -125,6 +135,7 @@ async def _async_main(
     include_submodules: bool = False,
     token: str | None = None,
     output: str | None = None,
+    mcp_server: bool = False,
 ) -> None:
     """Analyze a directory or repository and create a text dump of its contents.
 
@@ -161,6 +172,12 @@ async def _async_main(
         Raised if an error occurs during execution and the command must be aborted.
 
     """
+    # Check if MCP server mode is requested
+    if mcp_server:
+        from gitingest.mcp_server import start_mcp_server
+        await start_mcp_server()
+        return
+
     try:
         # Normalise pattern containers (the ingest layer expects sets)
         exclude_patterns = set(exclude_pattern) if exclude_pattern else set()

src/gitingest/entrypoint.py

@@ -134,14 +134,11 @@ async def ingest_async(
             logger.info("Starting local directory processing")
 
         if not include_gitignored:
-            logger.debug("Applying gitignore patterns")
             _apply_gitignores(query)
 
         logger.info("Processing files and generating output")
         summary, tree, content = ingest_query(query)
 
-        if output:
-            logger.debug("Writing output to file", extra={"output_path": output})
         await _write_output(tree, content=content, target=output)
 
         logger.info("Ingestion completed successfully")