Metadata-Version: 2.4
Name: iflow-mcp_saharcarmel-almanac
Version: 0.1.1
Summary: Documentation assistant leveraging Model Context Protocol
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: mcp[cli]>=1.5.0
Requires-Dist: httpx>=0.28.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"

# 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
