TheAlmanac

# 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash # For macOS: code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 3. Add TheAlmanac as an MCP server: ```json { "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 ```bash # Install development dependencies uv pip install -e ".[dev]" # Run tests uv run pytest ``` ## Adding Dependencies ```bash # Add a production dependency uv add package_name # Add a development dependency uv add --dev package_name ``` ## License MIT