xiaozhi-mcp: Instructions file for Codex

AGENTS.md - Guide for Agentic Coding

This document contains essential information for AI agents working on this repository.

Project Overview

xiaozhi-mcp is a Python-based MCP (Model Context Protocol) project that provides tool servers for AI capabilities including calculations, email, stock queries, todo management, and more. The project uses FastMCP to create stdio-based MCP servers.

Build/Install/Test Commands

Installation

# Recommended: Use uv for dependency management
uv sync

# Alternative: Use pip
pip install -r requirements.txt

Running the Application

# Run all configured servers from mcp_config.yaml
uv run python src/app.py

# Run a single server script
uv run python src/app.py src/mcp/tools/calculator.py

# Run with Docker
docker build -f docker/Dockerfile -t xiaozhi-mcp .
docker run -d --name xiaozhi-mcp -v $(pwd)/mcp_config.yaml:/app/mcp_config.yaml:ro xiaozhi-mcp

Testing

# No test framework is currently configured
# If pytest is added: pytest tests/; pytest tests/test_file.py::test_func

Linting/Type Checking

# No commands configured in pyproject.toml
# Common tools: ruff check ., ruff format ., mypy src/

Code Style Guidelines

File Structure

• Main application: src/app.py
• MCP tools: src/mcp/tools/*.py
• Each tool is a standalone FastMCP server with @mcp.tool() decorated functions
• Configuration: mcp_config.yaml (YAML format)

Imports

# Standard import order:
from fastmcp import FastMCP
import sys
import logging
# Third-party imports
import yaml
import json
from datetime import datetime
from typing import Optional, Dict, List, Any
# Local imports (if any)
from pathlib import Path
import uuid

Module Layout

# 1. File docstring (optional)
# 2. Imports
# 3. Windows UTF-8 encoding fix
if sys.platform == 'win32':
    sys.stderr.reconfigure(encoding='utf-8')
    sys.stdout.reconfigure(encoding='utf-8')
# 4. Logger setup
logger = logging.getLogger('ServerName')
# 5. Create MCP server
mcp = FastMCP("ServerName")
# 6. Constants (UPPER_CASE)
CONSTANT_NAME = "value"
# 7. Helper functions
# 8. Tool functions (@mcp.tool())
# 9. Main entry point
if __name__ == "__main__":
    mcp.run(transport="stdio")