Content
# 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
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors