tms-dev-mcp: Instructions file for Codex

Project Overview

Python MCP (Model Context Protocol) server providing tools to explore Omelet's Routing Engine and iNavi's Maps API for building Transport Management Systems. Built with FastMCP framework.

Provider Environment Notes

• iNavi Maps API: Use the production base URL (https://imaps.inavi.com) for runtime API calls, but keep the documentation URL pointed at the development docs host (https://dev-imaps.inavi.com/api-docs). Generated docs and tooling expect this split.

Build/Lint/Test Commands

Environment Setup

uv sync --all-groups          # Install all dependencies (dev + test groups)
source .venv/bin/activate     # Activate venv (Unix)
pre-commit install            # Install git hooks

Testing

uv run pytest -c setup.cfg                              # Run all tests
uv run pytest tests/test_tools/test_doc_tools.py       # Run single file
uv run pytest tests/test_tools/test_doc_tools.py::TestGetBasicInfo  # Run single class
uv run pytest tests/test_tools/test_doc_tools.py::TestGetBasicInfo::test_masks_api_keys  # Single test
uv run pytest -k "test_rejects"                        # Run tests matching pattern
uv run pytest -v                                       # Verbose output
uv run pytest --tb=short                               # Short traceback

Linting & Type Checking

uv run ruff check .              # Lint (will auto-fix with --fix)
uv run ruff format .             # Format code
uv run mypy tms_mcp              # Type check
uv run pre-commit run --all-files  # Run all hooks

Running the Server

uv run python -m tms_mcp.main                     # Start server (stdio)
uv run python -m tms_mcp.main update-docs         # Update all provider docs
uv run python -m tms_mcp.main update-docs omelet  # Update specific provider

Code Style Guidelines

Python Version & Type Hints

• Python 3.11+ required
• Use native collection types for type hints:

  # CORRECT
  def process(items: list[str], config: dict[str, Any]) -> tuple[int, str]: ...
  def fetch(url: str | None = None) -> dict[str, Any] | None: ...
  
  # WRONG - Do NOT use typing module equivalents
  from typing import List, Dict, Optional  # NO!
  

• Use Annotated[type, "description"] for MCP tool parameters