codedox

CodeDox is an AI-powered documentation search and code extraction toolchain. It crawls documentation sites, extracts code snippets with contextual data, and indexes them for fast search using PostgreSQL full-text search. It also exposes MCP (Model Context Protocol) endpoints over HTTP so AI assistants can query and retrieve relevant documentation and code snippets in context-aware conversations. The MCP endpoints are accessible at /mcp, and the system supports streamable HTTP transport per the MCP 2025-03-26 spec. To get started locally, deploy via Docker, configure your optional LLM API key, and use the web UI or MCP endpoints to browse, search, and extract code across docs. The UI provides a modern dashboard for managing crawls, versions, and health, while the MCP layer enables AI assistants to request contextually relevant documentation snippets in real time.

Prerequisites:

• Docker installed and running
• Git installed
• (Optional) access to an LLM API key for AI-enhanced extraction

Installation steps:

1. Clone the repository: git clone https://github.com/chriswritescode-dev/codedox.git cd codedox

2. Configure environment (if hosting locally):

   • Copy example env file and edit as needed: cp .env.example .env
   • Set CODE_LLM_API_KEY (optional) to your LLM provider key

3. Build and run using Docker (recommended):

   • If you have a prebuilt image, run: docker run -d --name codedox -p 5173:5173 -p 8000:8000 -e CODE_LLM_API_KEY="your-key" image-name
   • If you need to build locally, follow the project’s docker-setup.sh guidance or build the image as per the Dockerfile in the repo, then run the container similarly.

4. Verify the setup:

   • Access the UI at http://localhost:5173
   • Access MCP endpoints at http://localhost:8000/mcp

5. Documentation:

   • Full getting started guides and API references are available in the project’s online docs: https://chriswritescode-dev.github.io/codedox/

Tips and common considerations:

• Ensure your PostgreSQL instance is reachable and properly configured for full-text search if you’re hosting the database separately.
• The MCP integration is HTTP-based; if you’re behind a proxy, ensure proper routing to /mcp with streamable transport supported.
• The CODE_LLM_API_KEY (if provided) should be kept secure; consider using environment secrets in production.
• When crawling, configure URL patterns and domain restrictions to avoid unintended data collection.
• If you upgrade the container image, revisit the MCP endpoints to confirm compatibility with any protocol changes in the MCP spec.
• For debugging, check the health and crawl progress in the real-time dashboard and review logs for any extraction or indexing errors.