lunatask-mcp AGENTS.md

Repository Guidelines

Project Overview

LunaTask MCP is a Model Context Protocol server that provides a standardized bridge between AI models and the LunaTask API. It's designed as a lightweight, asynchronous Python application using the FastMCP framework, running as a local subprocess to enable AI tools to interact with LunaTask data.

Development Commands

Environment Setup

# Install dependencies and create virtual environment
uv sync

# Activate the virtual environment
source .venv/bin/activate

Code Quality and Testing

Always follow the guidelines in coding_guidelines

# Format and lint code
uv run ruff format
uv run ruff check --fix

# Type checking
uv run pyright

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_specific_file.py

# Run tests with coverage report
uv run pytest --cov=src/lunatask_mcp --cov-report=term-missing

# Run pre-commit hooks manually
uv run pre-commit run --all-files

Running the Application

# Run the MCP server (looks for ./config.toml by default)
uv run python -m lunatask_mcp
# or using the installed script
uv run lunatask-mcp

# Run with custom config file
uv run lunatask-mcp --config-file /path/to/config.toml

# Run with debug logging
uv run lunatask-mcp --log-level DEBUG

# Get help on available options
uv run lunatask-mcp --help

Configuration

The server requires a TOML configuration file with at minimum:

lunatask_bearer_token = "your_lunatask_bearer_token_here"

See config.example.toml for a complete configuration template.

Architecture

The project follows a single, event-driven monolith architecture:

• Core Framework: FastMCP for MCP protocol handling
• Transport: stdio for client communication
• External API: HTTPS requests to LunaTask API
• Concurrency: asyncio for non-blocking I/O
• Configuration: Pydantic for settings and validation

Key architectural patterns:

• Decorator-based configuration (@mcp.tool, @mcp.resource)
• Dependency injection for configuration and HTTP clients
• Repository pattern for LunaTask API interactions
• Asynchronous I/O throughout the stack