document-mcp AGENTS.md

Agent Usage Guide

The Document MCP system includes two AI agents that demonstrate how to use the MCP tools effectively. These agents are separate from the core MCP package and run directly from source code.

Latest Updates (v0.0.3)

• ✅ Pagination Support: All agents now work with the new pagination system for large documents
• ✅ GCP Observability: All tool calls now traced with logs/metrics (works locally too)
• ✅ OpenRouter Support: Use OpenRouter models with priority over OpenAI and Gemini
• ✅ Tool Selection Benchmarks: Evaluation framework for measuring agent tool selection accuracy
• ✅ Enhanced Testing: Complete test coverage with 536 tests passing (61% coverage)
• ✅ Improved Error Handling: Better timeout management for E2E scenarios

Prerequisites

1. Install the MCP package (for the core tools):

   pip install document-mcp
   

2. Clone the repository (for the agents):

   git clone https://github.com/your-org/document-mcp.git
   cd document-mcp
   

3. Install agent dependencies:

   uv sync --dev
   # or
   pip install -r requirements-agents.txt
   

4. Set up API keys (choose one, priority order: OpenRouter > OpenAI > Gemini):

   # For OpenRouter (recommended - access to multiple models)
   export OPENROUTER_API_KEY="your-openrouter-key"
   
   # For OpenAI
   export OPENAI_API_KEY="your-openai-key"
   
   # For Google Gemini
   export GEMINI_API_KEY="your-gemini-key"
   

   Or create a .env file in the project root (see .env.example).

Agent Types

Simple Agent

Best for: Quick operations, single-step tasks, structured JSON output

# Basic usage
uv run python src/agents/simple_agent/main.py --query "list all documents"

# With specific model
uv run python src/agents/simple_agent/main.py --query "create document 'Meeting Notes'" --model "gemini-2.5-flash"

# Interactive mode
uv run python src/agents/simple_agent/main.py --interactive

# Check configuration
uv run python src/agents/simple_agent/main.py --check-config