TheAlmanac

A documentation assistant leveraging Model Context Protocol (MCP) to help programmers access the most up-to-date and relevant information from API and software documentation.

Features

• Documentation Crawler: Automatically download and store documentation locally
• Simple Search: Find relevant documentation sections quickly
• MCP Integration: Provide LLMs with tools to access documentation
• File-based Storage: Efficiently organize documentation in a simple file structure
• MCP Server: HTTP server for LLM tool access

Installation

# Clone the repository
git clone https://github.com/yourusername/TheAlmanac.git
cd TheAlmanac

# Install dependencies with UV
uv pip install -e .

Usage

Managing Documentation Sources

# Add a documentation source
almanac add python https://docs.python.org/3/

# List all documentation sources
almanac list

# Download documentation
almanac download python

# Remove a documentation source
almanac remove python

Searching Documentation

# Search all documentation
almanac search "context manager"

# Search a specific source
almanac search "context manager" --source python

# Search with more context
almanac search "context manager" --context-lines 5

Running the MCP Server

# Start the HTTP server (for direct API access)
almanac serve --transport http

# Start the MCP server (for integration with MCP clients like Claude for Desktop)
almanac serve --transport stdio

# Start on a specific host and port (for HTTP transport)
almanac serve --transport http --host 0.0.0.0 --port 9000

MCP Tools

TheAlmanac provides the following MCP tools:

1. search_documentation: Search for relevant documentation
2. get_documentation: Get a specific document or section
3. download_documentation: Download a new documentation source
4. list_documentation: List available documentation sources

Example Scripts

The scripts directory contains example scripts for testing and demonstrating TheAlmanac:

• test_mcp_tools.py: Directly test MCP tools
• test_mcp_server.py: Test the MCP server with HTTP requests
• test_mcp_fastmcp.py: Test the FastMCP implementation directly
• example_workflow.py: Run a complete workflow example

Example MCP Tool Usage

# Test the search tool (HTTP server)
./scripts/test_mcp_tools.py search "installation"

# Test getting a specific document (HTTP server)
./scripts/test_mcp_tools.py get python index.md

# Test the search tool (FastMCP)
./scripts/test_mcp_fastmcp.py search "installation"

# Test listing documentation (FastMCP)
./scripts/test_mcp_fastmcp.py list

# Test the complete workflow
./scripts/example_workflow.py

MCP Integration with Claude for Desktop

To integrate TheAlmanac with Claude for Desktop:

1. Make sure Claude for Desktop is installed

2. Edit the Claude for Desktop configuration file:

   # For macOS:
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

3. Add TheAlmanac as an MCP server:

   {
     "mcpServers": {
       "the-almanac": {
         "command": "/path/to/python",
         "args": [
           "-m",
           "almanac.cli.commands",
           "serve",
           "--transport",
           "stdio"
         ]
       }
     }
   }
   

4. Restart Claude for Desktop

5. Look for the hammer icon to access TheAlmanac tools

Development

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

Adding Dependencies

# Add a production dependency
uv add package_name

# Add a development dependency
uv add --dev package_name

License

MIT