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 <noreply@anthropic.com>

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

@@ -54,6 +54,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"
 
@@ -132,3 +137,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")