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:
- search_documentation: Search for relevant documentation
- get_documentation: Get a specific document or section
- download_documentation: Download a new documentation source
- 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 toolstest_mcp_server.py: Test the MCP server with HTTP requeststest_mcp_fastmcp.py: Test the FastMCP implementation directlyexample_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:
-
Make sure Claude for Desktop is installed
-
Edit the Claude for Desktop configuration file:
# For macOS: code ~/Library/Application\ Support/Claude/claude_desktop_config.json
-
Add TheAlmanac as an MCP server:
{ "mcpServers": { "the-almanac": { "command": "/path/to/python", "args": [ "-m", "almanac.cli.commands", "serve", "--transport", "stdio" ] } } }
-
Restart Claude for Desktop
-
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
Metadata
Release files for iflow-mcp_saharcarmel-almanac 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_saharcarmel_almanac-0.1.1.tar.gz | 24.9 kB | Without provenance | Details for iflow_mcp_saharcarmel_almanac-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_saharcarmel_almanac-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_saharcarmel_almanac-0.1.1-py3-none-any.whl |
Total release size: 59.1 kB
Release files / iflow_mcp_saharcarmel_almanac-0.1.1.tar.gz
| Download URL | iflow_mcp_saharcarmel_almanac-0.1.1.tar.gz |
|---|---|
| Size | 24.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
09f742a44122412ccf5b7926bde1a6326828ce9c2a5c173910b8f536ec51e345
|
|
BLAKE2b-256 checksum How to use checksums |
40930a9e2f1bd5079cdfea3c78e0596ea14c8a6911ebc298f3fb301e4be2986c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_saharcarmel_almanac-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_saharcarmel_almanac-0.1.1-py3-none-any.whl |
|---|---|
| Size | 34.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fd558509540397e70793a025908b6c2f962b3295463dc7eb16ad69c118a9fc0f
|
|
BLAKE2b-256 checksum How to use checksums |
fb8ccee1deefe8a3075a6235bc98c6b8c41fcc2a508828e2dcc1045e186a9262
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_saharcarmel-almanac 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.