M365-roadmap-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Model Context Protocol (MCP) server that enables AI agents to query the Microsoft 365 Roadmap programmatically. The server provides structured access to Microsoft's public roadmap API, allowing agents to answer complex filtering questions about upcoming M365 features, release dates, and cloud instance availability (particularly critical for government/defense clients using GCC, GCC High, or DoD instances).

Key API Endpoint: https://www.microsoft.com/releasecommunications/api/v2/m365

Architecture Pattern

This project follows a standard MCP server architecture:

Directory Structure

src/
  <server_name>_mcp/
    server.py           # FastMCP server initialization with stdio/HTTP transport
    models/             # Pydantic models for data structures
    feeds/              # Data fetching and parsing logic
    tools/              # MCP tool implementations (async functions)
      __init__.py
      <tool_name>.py    # Each tool in its own module
tests/
  test_tools.py         # pytest-based tests for MCP tools
  test_feeds.py         # Tests for data fetching

Core Components

1. Server Entry Point (server.py)

• Uses FastMCP library for MCP protocol implementation
• Supports dual transport: stdio (default for MCP client auto-start) and HTTP (for remote access)
• Transport selection via MCP_TRANSPORT environment variable
• Registers tools using mcp.tool() decorator
• Includes server instructions for AI agents

2. Tool Implementation Pattern

• Each tool is an async function in tools/ directory
• Tools accept typed parameters (leveraging Python type hints)
• Return structured dictionaries with results
• Include comprehensive docstrings describing usage, parameters, and return values
• Example tool structure:

  async def tool_name(
      param1: str | None = None,
      param2: int = 10,
  ) -> dict:
      """Tool description.
  
      Args:
          param1: Description
          param2: Description
  
      Returns:
          Dictionary with results
      """