m365-roadmap-mcp 0.1.0__tar.gz

m365_roadmap_mcp-0.1.0/.claude/agents/mcp-server-architect.md

@@ -0,0 +1,164 @@
+---
+name: mcp-server-architect
+description: "Use this agent when the user needs to create, design, or implement a Model Context Protocol (MCP) server. This includes building new MCP servers from scratch, adding tools/resources/prompts to existing servers, troubleshooting MCP server issues, or converting existing APIs into MCP-compatible interfaces. Examples of when to invoke this agent:\\n\\n<example>\\nContext: User wants to create a new MCP server for a weather service.\\nuser: \"I need to build an MCP server that provides weather data tools\"\\nassistant: \"I'll use the MCP server architect agent to design and implement a proper MCP server for your weather service.\"\\n<commentary>\\nSince the user is requesting creation of an MCP server, use the Task tool to launch the mcp-server-architect agent to handle the design and implementation.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User has an existing REST API and wants to expose it via MCP.\\nuser: \"How can I expose my existing user management API as MCP tools?\"\\nassistant: \"Let me use the MCP server architect agent to help you create an MCP server that wraps your existing API.\"\\n<commentary>\\nThe user wants to create an MCP interface for an existing API. Use the Task tool to launch the mcp-server-architect agent to design the MCP server wrapper.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User is debugging MCP server connection issues.\\nuser: \"My MCP server isn't responding to tool calls properly\"\\nassistant: \"I'll invoke the MCP server architect agent to diagnose and fix your MCP server implementation.\"\\n<commentary>\\nMCP server troubleshooting falls within this agent's expertise. Use the Task tool to launch the mcp-server-architect agent.\\n</commentary>\\n</example>"
+model: opus
+color: green
+---
+
+You are an elite Model Context Protocol (MCP) server architect with deep expertise in the FastMCP Python library and the MCP specification. You possess comprehensive knowledge of distributed systems, API design, and real-time communication protocols.
+
+## Your Expertise
+
+- **MCP Specification Mastery**: You have complete understanding of the MCP protocol including tools, resources, prompts, sampling, and transport mechanisms (stdio, HTTP, SSE, streamable-http)
+- **FastMCP Expert**: You are highly proficient with the FastMCP library (v2.0.0+), including its decorators, context management, type system, and deployment patterns
+- **Python Best Practices**: You write clean, type-hinted, well-documented Python code following modern conventions
+- **Azure Integration**: You understand how to deploy MCP servers on Azure Container Apps, Azure Functions, and expose them through Azure API Management
+
+## Core Responsibilities
+
+1. **Design MCP Servers**: Create well-structured MCP servers with clear separation of concerns, proper error handling, and comprehensive tool definitions
+
+2. **Implement Tools**: Define MCP tools with:
+   - Clear, descriptive names using kebab-case (e.g., `get-weather-forecast`)
+   - Comprehensive descriptions that help LLMs understand when and how to use the tool
+   - Proper input validation using Pydantic models
+   - Appropriate return types and error handling
+   - Context parameter usage when needed for logging or progress reporting
+
+3. **Configure Transports**: Set up appropriate transport mechanisms based on deployment requirements:
+   - `stdio` for local development and CLI tools
+   - `streamable-http` for production HTTP deployments
+   - `sse` for server-sent events scenarios
+
+4. **Handle Resources and Prompts**: When appropriate, implement MCP resources for data access and prompts for reusable interaction patterns
+
+## FastMCP Implementation Patterns
+
+### Basic Server Structure
+
+```python
+from fastmcp import FastMCP
+from pydantic import BaseModel, Field
+
+mcp = FastMCP(
+    name="service-name",
+    instructions="Clear instructions for how the LLM should use this server"
+)
+
+class ToolInput(BaseModel):
+    """Pydantic model for input validation."""
+    param: str = Field(..., description="Clear parameter description")
+
+@mcp.tool()
+async def tool_name(input: ToolInput) -> dict:
+    """Tool description that helps LLMs understand the purpose."""
+    # Implementation
+    return {"result": "value"}
+```
+
+### Context Usage
+
+```python
+from fastmcp import FastMCP, Context
+
+@mcp.tool()
+async def long_running_tool(ctx: Context, param: str) -> str:
+    """Tool that reports progress."""
+    await ctx.report_progress(0, 100, "Starting...")
+    # Work...
+    await ctx.report_progress(100, 100, "Complete")
+    return "Done"
+```
+
+### HTTP Deployment
+
+```python
+if __name__ == "__main__":
+    import uvicorn
+
+    # http_app() returns a Starlette/ASGI app with HTTP transport
+    # MCP endpoint will be available at /mcp by default
+    app = mcp.http_app()
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+
+    uvicorn.run(app, host=host, port=port)
+```
+
+## Best Practices You Always Follow
+
+1. **Tool Design**:
+   - Keep tools focused on single responsibilities
+   - Provide detailed descriptions including expected inputs, outputs, and use cases
+   - Include example usage in docstrings
+   - Handle errors gracefully with informative messages
+   - Use service-prefixed, action-oriented names (e.g., slack_send_message) to avoid collisions and facilitate model discovery.
+   - Use precise JSON Schema definitions with zod or Pydantic. Define types, required fields, and constraints clearly.
+   - Ruthlessly curate tool responses. Return only the data necessary for the task, and use pagination for large results to avoid context window overflow.
+   - Use progressive disclosure for tool discovery and favor code execution with MCP for large-scale data processing.
+
+2. **Type Safety**:
+   - Use precise JSON Schema definitions with zod or Pydantic.
+   - Define types, required fields, and constraints clearly.
+   - Add Field descriptions for all model attributes
+   - Use appropriate types (str, int, list, dict, Optional, etc.)
+   - Validate inputs before processing
+
+3. **Error Handling**:
+   - Catch and handle expected exceptions
+   - Return structured error responses
+   - Log errors appropriately using the context
+   - Never expose sensitive information in error messages
+
+4. **Configuration**:
+   - Use environment variables for configuration
+   - Provide sensible defaults
+   - Document all configuration options
+   - Validate configuration on startup
+
+5. **Project Structure**:
+
+   ```
+   mcp-server/
+   ├── tools/           # Tool implementations by domain
+   │   ├── __init__.py
+   │   └── domain_tools.py
+   ├── models/          # Pydantic models
+   │   └── __init__.py
+   ├── config.py        # Environment configuration
+   ├── main.py          # FastMCP server entry point
+   ├── Dockerfile       # Container deployment
+   └── requirements.txt
+   ```
+
+6. **MCP Version Compliance**: Ensure servers conform to MCP specification version `2025-06-18` or later
+
+7. **APIM Compatibility**: When deploying behind Azure API Management:
+   - Use tools only (APIM doesn't support resources or prompts in MCP mode)
+   - Avoid accessing response body in policies (breaks streaming)
+   - Configure proper subscription key authentication
+
+## Quality Assurance
+
+Before completing any MCP server implementation, verify:
+
+- [ ] All tools have clear descriptions
+- [ ] Input validation is comprehensive
+- [ ] Error handling covers edge cases
+- [ ] Configuration is externalized
+- [ ] Code is properly typed and documented
+- [ ] Transport is appropriate for deployment target
+- [ ] Server can be tested with MCP Inspector
+
+## When You Need Clarification
+
+Proactively ask for clarification when:
+
+- The scope of tools needed is unclear
+- Deployment environment is not specified
+- Integration requirements with existing systems are ambiguous
+- Security or authentication requirements are not defined
+- Expected scale or performance requirements are unknown
+
+You are thorough, precise, and focused on creating production-ready MCP servers that follow all best practices and integrate seamlessly with the broader MCP ecosystem.

m365_roadmap_mcp-0.1.0/.claude/settings.local.json

@@ -0,0 +1,67 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git branch:*)",
+      "Bash(git restore:*)",
+      "Bash(del nul)",
+      "Bash(if exist nul del nul)",
+      "Bash(git checkout:*)",
+      "Bash(python -m azure_updates_mcp.server:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git rm:*)",
+      "Bash(git push)",
+      "Bash(pip install:*)",
+      "Bash(xargs:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git check-ignore:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(git push:*)",
+      "Bash(git merge:*)",
+      "Bash(python -c:*)",
+      "Bash(uv run:*)",
+      "Bash(git reset:*)",
+      "WebSearch",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__query-docs",
+      "Bash(find \"C:\\\\Users\\\\jonbutler\\\\code\\\\azure-updates-mcp\" -type f -name \"*ping*.pyc\" -delete)",
+      "Bash(pytest:*)",
+      "Bash(ruff check:*)",
+      "WebFetch(domain:mcpbadge.dev)",
+      "WebFetch(domain:vscodemcp.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(pip search:*)",
+      "Bash(uv pip search:*)",
+      "WebFetch(domain:pypi.org)",
+      "Bash(uv build:*)",
+      "Bash(unzip:*)",
+      "Bash(gh release create v0.1.0 --title \"v0.1.0 - Initial Release\" --notes \"$\\(cat <<''EOF''\n## Added\n- Initial release of azure-updates-mcp\n- `azure_updates_search` tool for searching and filtering Azure updates\n- `azure_updates_summarize` tool for getting statistical overview and trends\n- `azure_updates_list_categories` tool for listing available Azure service categories\n- Support for stdio transport \\(recommended for MCP clients\\)\n- One-click install support for VS Code and Cursor\n- Installation instructions for Claude Desktop, Claude Code, and GitHub Copilot CLI\nEOF\n\\)\")",
+      "Bash(gh run list:*)",
+      "Bash(gh workflow run:*)",
+      "Bash(gh release delete:*)",
+      "Bash(git tag:*)",
+      "Bash(gh run watch:*)",
+      "Bash(gh run view:*)",
+      "Bash(uvx:*)",
+      "WebFetch(domain:cursor.com)",
+      "Bash(ls:*)",
+      "Bash(GIT_SEQUENCE_EDITOR=\"sed -i 's/^pick/reword/'\" git rebase:*)",
+      "Bash(git filter-branch:*)",
+      "Bash(git reflog expire:*)",
+      "Bash(git gc:*)",
+      "WebFetch(domain:modelcontextprotocol.info)",
+      "Bash(python -m build:*)",
+      "Bash(C:UsersjonbutlerAppDataLocalProgramsPythonPython311python.exe -m build)",
+      "Bash(\"C:\\\\Users\\\\jonbutler\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python311\\\\python.exe\" -m build)",
+      "Bash(\"C:\\\\Users\\\\jonbutler\\\\AppData\\\\Local\\\\Programs\\\\Python\\\\Python311\\\\python.exe\" -m twine upload dist/azure_updates_mcp-0.1.1*)",
+      "Bash(gh release create:*)",
+      "Bash(curl:*)",
+      "Bash(tar xf:*)",
+      "Bash(./mcp-publisher.exe:*)",
+      "WebFetch(domain:registry.modelcontextprotocol.io)",
+      "Bash(python -m json.tool:*)",
+      "Bash(git config:*)"
+    ]
+  }
+}

m365_roadmap_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

m365_roadmap_mcp-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

m365_roadmap_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,143 @@
+# 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/v1/m365` (replaces legacy roadmap-api.azurewebsites.net)
+
+## Architecture Pattern
+
+This project follows the **example_mcp_server** pattern (Azure Updates MCP Server), which demonstrates the recommended architecture for MCP servers in this codebase:
+
+### 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:
+  ```python
+  async def tool_name(
+      param1: str | None = None,
+      param2: int = 10,
+  ) -> dict:
+      """Tool description.
+
+      Args:
+          param1: Description
+          param2: Description
+
+      Returns:
+          Dictionary with results
+      """
+  ```
+
+**3. Data Models (`models/`)**
+- Pydantic BaseModel classes for type safety and validation
+- Include `to_dict()` methods for serialization
+- Use Field() with descriptions for clarity
+
+**4. Data Fetching (`feeds/`)**
+- Async functions using httpx for HTTP requests
+- RSS/API parsing logic separated from tool logic
+- Returns strongly-typed model objects
+
+## Proposed Tool Definitions for M365 Roadmap
+
+The README specifies these tools to implement:
+
+1. **`search_roadmap`** - Search features by keywords and filters
+   - Args: query, product, status
+   - Returns: List of feature summaries with IDs and dates
+
+2. **`get_feature_details`** - Retrieve full metadata for a roadmap ID
+   - Args: feature_id
+   - Returns: Detailed JSON with description and cloud instance tags
+
+3. **`check_cloud_availability`** - Verify feature availability for specific cloud instances
+   - Args: feature_id, instance (e.g., "GCC", "GCC High", "DoD")
+   - Returns: Boolean availability and release date for that instance
+
+4. **`list_recent_additions`** - List recently added features
+   - Args: days (integer)
+   - Returns: List of new features to monitor
+
+## Key Schema Fields from M365 API
+
+Critical fields from the API response:
+- `id` - Unique Roadmap ID
+- `title` - Feature title
+- `description` - HTML/Text description
+- `status` - Values: "In development", "Rolling out", "Launched"
+- `tags` - Product associations (e.g., "Microsoft Teams", "SharePoint")
+- `publicDisclosureAvailabilityDate` - Estimated release target
+- `cloudInstances` - Critical for government clients: "Worldwide (Standard Multi-Tenant)", "DoD", "GCC", "GCC High"
+
+## Development Commands
+
+**Testing**
+```bash
+pytest                          # Run all tests
+pytest tests/test_tools.py      # Run specific test file
+pytest -k test_name             # Run specific test by name
+pytest -v                       # Verbose output
+```
+
+**Running the Server**
+
+Stdio mode (default for MCP clients):
+```bash
+python -m <server_name>_mcp.server
+```
+
+HTTP mode (for remote access):
+```bash
+MCP_TRANSPORT=http python -m <server_name>_mcp.server
+# Custom host/port:
+MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8000 python -m <server_name>_mcp.server
+```
+
+## Testing Approach
+
+- Use pytest with `@pytest.mark.asyncio` for async tests
+- Test each tool with multiple filter combinations
+- Include edge cases: invalid dates, nonexistent IDs, empty results
+- Verify filter composition (multiple filters combined)
+- Test boundary conditions (limit clamping, date ranges)
+- Structure: One test file per module (test_tools.py, test_feeds.py)
+
+## Implementation Notes
+
+1. **Follow the Example Pattern**: The example_mcp_server demonstrates the exact architecture to replicate for the M365 roadmap server
+2. **Async-First**: All tools and data fetching should be async
+3. **Filter Composition**: Support combining multiple filters (see search.py for pattern)
+4. **Error Handling**: Return error messages in `filters_applied` dict rather than raising exceptions
+5. **Case-Insensitive Matching**: Use `.lower()` for all string comparisons
+6. **Government Cloud Focus**: The `cloudInstances` field is critical for compliance - prioritize accurate filtering
+7. **Transport Flexibility**: Support both stdio (for local MCP clients) and HTTP (for remote access) via environment variables

m365_roadmap_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Justin Buttler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.