What is Thealmanac

TheAlmanac is a documentation assistant that utilizes the Model Context Protocol (MCP) to help programmers access the most current and relevant information from API and software documentation.

Use cases

Use cases for TheAlmanac include searching for specific programming concepts, downloading documentation for offline access, and integrating with LLMs for enhanced programming assistance.

How to use

To use TheAlmanac, clone the repository, install dependencies, and manage documentation sources using commands like ‘almanac add’, ‘almanac download’, and ‘almanac search’. You can also run the MCP Server for direct API access.

Key features

Key features of TheAlmanac include a Documentation Crawler for automatic downloads, Simple Search for quick access to documentation sections, MCP Integration for LLMs, File-based Storage for organized documentation, and an MCP Server for tool access.

Where to use

TheAlmanac can be used in software development environments, particularly where programmers need quick access to documentation for APIs and libraries.

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