nagoya-bus-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI Coding Agent such as Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server providing tools to query Nagoya City bus timetables. Built using FastMCP, it exposes MCP tools and prompts that allow LLMs to interact with the Nagoya City bus API.

Development Commands

Setup

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

Testing

# Run all tests (excluding integration tests)
uv run pytest

# Run integration tests
uv run pytest -m integration

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

# Run with coverage
uv run pytest --cov

Linting and Type Checking

# Run all pre-commit checks
uv run pre-commit run --all-files

# Run type checking
uv run mypy

# Format and lint (via pre-commit hooks: ruff)
uv run pre-commit run ruff-check --all-files
uv run pre-commit run ruff-format --all-files

Running the Server

# Run with MCP Inspector (recommended for development)
npx @modelcontextprotocol/inspector uv run nagoya-bus-mcp

# Run directly
uv run nagoya-bus-mcp

# Try API client directly
uv run python -m nagoya_bus_mcp.client

Building

# Build package
uv build

Architecture

Project Structure

src/
└── nagoya_bus_mcp/
    ├── __main__.py           # Entry point for the MCP server
    ├── client.py             # HTTP client for Nagoya Bus API
    ├── approach.py           # Wrapper and utilities for real-time approach information
    ├── data.py               # Common base data (stations, poles) with caching
    ├── mcp/
    │   ├── server.py         # FastMCP server initialization and lifespan
    │   ├── tools.py          # MCP tool implementations
    │   └── prompts.py        # MCP prompt templates
    └── version.py            # Auto-generated version file (from setuptools-scm)

demo/                         # Example integrations with AI agent frameworks
tests/                        # Test suite with unit and integration tests