mcp-server-mattermost: Instructions file for Codex

CLAUDE.md

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

Project Overview

MCP server for Mattermost integration. Exposes Mattermost REST API operations as MCP tools for AI assistants (Claude Desktop, Cursor).

Architecture:

MCP Client (Claude Desktop, Cursor)
    ↓ (stdio JSON-RPC)
FastMCP Server
    ├── Tools Layer (channels, messages, posts, users, teams, files, bookmarks)
    ├── Pydantic Models (validation + schema generation)
    └── MattermostClient (async HTTP with retry)
        ↓ (HTTPS)
Mattermost Server (REST API v4)

Documentation References

• FastMCP: https://gofastmcp.com/llms.txt - Use for implementation details when working with FastMCP
• Mattermost API: https://api.mattermost.com/ - REST API v4 reference

Commands

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run specific test file
uv run pytest tests/test_config.py -v

# Lint
uv run ruff check src tests

# Format
uv run ruff format src tests

# Type check
uv run mypy src

# Run the server
uv run mcp-server-mattermost

Code Style

• Python 3.10+ (use list[], dict[], X | None syntax)
• 120-character line length
• Google-style docstrings
• Type hints required (mypy strict mode)
• Two blank lines after imports
• Ruff with ALL rules enabled (see pyproject.toml for exceptions)

Key Source Files

• src/mcp_server_mattermost/__init__.py - Package entry, exports main() and __version__
• src/mcp_server_mattermost/server.py - FastMCP instance creation, lifespan, FileSystemProvider
• src/mcp_server_mattermost/deps.py - Dependency injection providers (get_client)
• src/mcp_server_mattermost/auth.py - MattermostTokenVerifier for per-client token auth
• src/mcp_server_mattermost/client.py - Async HTTP client with retry logic
• src/mcp_server_mattermost/config.py - Settings via pydantic-settings (env vars prefixed MATTERMOST_)
• src/mcp_server_mattermost/exceptions.py - Exception hierarchy (MattermostMCPError base)
• src/mcp_server_mattermost/logging.py - Logging setup (stderr per MCP spec)
• src/mcp_server_mattermost/middleware.py - FastMCP middleware for error handling
• src/mcp_server_mattermost/enums.py - Capability and ToolTag enums for tool metadata
• src/mcp_server_mattermost/tools/ - MCP tool implementations by category
• src/mcp_server_mattermost/models/ - Pydantic models for validation