cpp_style_server.py

"""
C++ 编码规范 MCP 服务器

提供 C++ 代码规范检查、最佳实践建议和代码审查支持。
"""

import os
from pathlib import Path
from typing import Literal

from mcp.server.fastmcp import FastMCP
from mcp.types import ToolAnnotations
from starlette.requests import Request
from starlette.responses import FileResponse, JSONResponse, RedirectResponse

# 导入工具模块
from cpp_style.tools.naming_checker import get_checker as get_naming_checker
from cpp_style.tools.include_guard_checker import get_checker as get_include_guard_checker
from cpp_style.tools.memory_safety import get_analyzer as get_memory_analyzer
from cpp_style.tools.modern_cpp import get_suggester as get_modern_cpp_suggester
from cpp_style.tools.const_checker import get_checker as get_const_checker

# 导入资源模块
from cpp_style.resources.naming_rules import get_resource as get_naming_resource
from cpp_style.resources.best_practices import get_resource as get_practices_resource
from cpp_style.resources.cpp_standards import get_resource as get_standards_resource
from cpp_style.resources.design_patterns import get_resource as get_patterns_resource

# 导入提示模块
from cpp_style.prompts.code_review import get_prompt as get_code_review_prompt
from cpp_style.prompts.refactor_suggestion import get_prompt as get_refactor_prompt

# ==================== OAuth 配置 ====================

# GitHub OAuth 环境变量（在 Railway 中配置）
_GITHUB_CLIENT_ID = os.environ.get("GITHUB_CLIENT_ID", "")
_GITHUB_CLIENT_SECRET = os.environ.get("GITHUB_CLIENT_SECRET", "")
# MCP 服务器公开 URL（Railway 部署地址或自定义域名）
_MCP_SERVER_URL = os.environ.get(
    "MCP_SERVER_URL",
    "https://cpp-style-guide-mcp.fly.dev",
)

_oauth_provider = None
_auth_settings = None

if _GITHUB_CLIENT_ID and _GITHUB_CLIENT_SECRET:
    from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
    from mcp.server.auth.provider import ProviderTokenVerifier
    from cpp_style.auth.github_provider import GitHubOAuthProvider

    _oauth_provider = GitHubOAuthProvider(
        github_client_id=_GITHUB_CLIENT_ID,
        github_client_secret=_GITHUB_CLIENT_SECRET,
        mcp_server_url=_MCP_SERVER_URL,
    )
    _auth_settings = AuthSettings(
        issuer_url=_MCP_SERVER_URL,  # type: ignore[arg-type]
        resource_server_url=_MCP_SERVER_URL,  # type: ignore[arg-type]
        client_registration_options=ClientRegistrationOptions(
            enabled=True,
            valid_scopes=["mcp"],
            default_scopes=["mcp"],
        ),
    )

# 创建 MCP 服务器实例
# stateless_http=True：每个请求独立处理，无需 session ID
# 使 Smithery 扫描器可以直接查询 tools/list 等端点
mcp = FastMCP(
    "C++ Style Guide Server",
    auth_server_provider=_oauth_provider,
    token_verifier=ProviderTokenVerifier(_oauth_provider) if _oauth_provider else None,
    auth=_auth_settings,
    stateless_http=True,
)


# ==================== Custom Routes ====================

@mcp.custom_route("/health", methods=["GET"])
async def health_check(request: Request) -> JSONResponse:
    """健康检查端点（供 Railway 等平台使用）"""
    auth_enabled = _oauth_provider is not None
    return JSONResponse({
        "status": "ok",
        "service": "cpp-style-guide-mcp",
        "auth": "github" if auth_enabled else "disabled",
    })


@mcp.custom_route("/.well-known/mcp/server-card.json", methods=["GET"])
async def server_card(request: Request) -> FileResponse | JSONResponse:
    """Smithery 服务器元数据（用于 Smithery 平台展示）"""
    card_path = Path(__file__).parent / "static" / ".well-known" / "mcp" / "server-card.json"
    if card_path.exists():
        return FileResponse(str(card_path), media_type="application/json")
    return JSONResponse({"error": "server-card.json 未找到"}, status_code=404)


@mcp.custom_route("/icon.svg", methods=["GET"])
async def server_icon(request: Request) -> FileResponse | JSONResponse:
    """服务器图标"""
    icon_path = Path(__file__).parent / "static" / "icon.svg"
    if icon_path.exists():
        return FileResponse(str(icon_path), media_type="image/svg+xml")
    return JSONResponse({"error": "icon.svg 未找到"}, status_code=404)


@mcp.custom_route("/oauth/callback", methods=["GET"])
async def oauth_callback(request: Request) -> RedirectResponse | JSONResponse:
    """GitHub OAuth 回调处理（GitHub 授权后重定向到此路由）"""
    if _oauth_provider is None:
        return JSONResponse({"error": "OAuth 未启用"}, status_code=400)

    code = request.query_params.get("code")
    state = request.query_params.get("state")

    if not code or not state:
        return JSONResponse({"error": "缺少 code 或 state 参数"}, status_code=400)

    try:
        redirect_url = await _oauth_provider.handle_github_callback(code, state)
        return RedirectResponse(url=redirect_url, status_code=302)
    except ValueError as e:
        return JSONResponse({"error": str(e)}, status_code=400)


# ==================== Tools ====================

_READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False)


@mcp.tool(
    description="Check whether a C++ identifier follows naming conventions. Validates variables, constants, functions, classes, namespaces, member variables, template parameters, and file names against established C++ style guidelines. Returns whether the identifier is valid, a detailed explanation, and suggested alternatives if it violates the rules.",
    annotations=_READ_ONLY,
)
def check_naming(
    identifier: str,
    category: Literal["variable", "constant", "function", "class", "namespace", "member_variable", "template_parameter", "file_naming"],
) -> str:
    """
    检查 C++ 标识符命名是否符合规范

    参数:
        identifier: 要检查的标识符名称
        category: 标识符类别（variable/constant/function/class/namespace/member_variable/template_parameter/file_naming）

    返回:
        检查结果，包含是否符合规范、详细说明和建议
    """
    checker = get_naming_checker()
    is_valid, details, suggestions = checker.check_naming(identifier, category)

    result = details
    if suggestions:
        result += f"\n推荐使用:\n"
        for sug in suggestions:
            result += f"  • {sug}\n"

    return result


@mcp.tool(
    description="Check whether a C++ header file has correct include guards or #pragma once directives. Detects missing guards, malformed macro names, mismatched #endif comments, and suggests correctly formatted guard macros based on the file path.",
    annotations=_READ_ONLY,
)
def check_include_guard(code: str, file_path: str = "") -> str:
    """
    检查 C++ 头文件的包含保护是否正确

    参数:
        code: 头文件的完整代码
        file_path: 可选的文件路径，用于生成建议的保护宏名

    返回:
        检查结果，包含是否符合规范、详细说明和建议
    """
    checker = get_include_guard_checker()

    file_path_param = file_path if file_path else None
    is_valid, details, suggestions = checker.check_include_guard(code, file_path_param)

    result = details
    if suggestions and not is_valid:
        result += f"\n建议的保护宏名:\n"
        for sug in suggestions:
            result += f"  • {sug}\n"

    return result


@mcp.tool(
    description="Analyze C++ code for memory safety issues including memory leaks, dangling pointers, double-free errors, use of raw owning pointers, missing RAII patterns, and unsafe array operations. Returns a detailed report with line-level findings and recommendations to use modern C++ alternatives like smart pointers.",
    annotations=_READ_ONLY,
)
def analyze_memory_safety(code: str) -> str:
    """
    分析 C++ 代码中的内存安全问题

    参数:
        code: 要分析的 C++ 代码

    返回:
        内存安全分析报告，包括潜在的内存泄漏、悬空指针、不安全操作等
    """
    analyzer = get_memory_analyzer()
    issues, report = analyzer.analyze_memory_safety(code)
    return report


@mcp.tool(
    description="Suggest how to modernize C++ code to use features from a target standard (C++11 through C++23). Identifies outdated patterns such as raw loops replaceable by range-for, C-style casts, manual memory management, pre-C++11 type aliases, and suggests concrete rewrites using modern idioms like auto, structured bindings, std::optional, concepts, and ranges.",
    annotations=_READ_ONLY,
)
def suggest_modern_cpp(
    code: str,
    target_standard: Literal["cpp11", "cpp14", "cpp17", "cpp20", "cpp23"] = "cpp17",
) -> str:
    """
    建议将代码升级为现代 C++ 写法

    参数:
        code: 要分析的 C++ 代码
        target_standard: 目标 C++ 标准（cpp11/cpp14/cpp17/cpp20/cpp23，默认 cpp17）

    返回:
        现代化建议报告，包括可以使用的新特性和重写示例
    """
    suggester = get_modern_cpp_suggester()
    suggestions, report = suggester.suggest_modern_cpp(code, target_standard)
    return report


@mcp.tool(
    description="Check C++ code for const correctness issues. Identifies member functions that do not modify state but are missing the const qualifier, non-const references where const references would suffice, and variables that are never modified but not declared const. Returns a report with specific locations and suggested fixes.",
    annotations=_READ_ONLY,
)
def check_const_correctness(code: str) -> str:
    """
    检查 C++ 代码中的 const 正确性

    参数:
        code: 要检查的 C++ 代码

    返回:
        const 正确性检查报告，包括缺少 const 的地方和改进建议
    """
    checker = get_const_checker()
    issues, report = checker.check_const_correctness(code)
    return report


# ==================== Resources ====================

@mcp.resource("cpp-style://naming/{category}")
def get_naming_convention(category: str) -> str:
    """
    获取 C++ 命名规范文档

    可用的类别:
    - variable: 变量命名
    - constant: 常量命名
    - function: 函数命名
    - class: 类命名
    - namespace: 命名空间命名
    - member_variable: 成员变量命名
    - template_parameter: 模板参数命名
    - file_naming: 文件命名
    - all: 查看所有类别
    """
    resource = get_naming_resource()

    if category == "all":
        return resource.get_all_categories()

    return resource.get_naming_rule(category)


@mcp.resource("cpp-style://best-practices/{topic}")
def get_best_practice(topic: str) -> str:
    """
    获取 C++ 最佳实践指南

    可用的主题:
    - memory: 内存管理
    - exceptions: 异常处理
    - templates: 模板编程
    - concurrency: 并发编程
    - performance: 性能优化
    - modern_cpp: 现代 C++ 特性
    - all: 查看所有主题
    """
    resource = get_practices_resource()

    if topic == "all":
        return resource.get_all_topics()

    return resource.get_best_practice(topic)


@mcp.resource("cpp-style://standard/{version}")
def get_cpp_standard(version: str) -> str:
    """
    获取 C++ 标准特性文档

    可用的版本:
    - cpp11: C++11 特性
    - cpp14: C++14 特性
    - cpp17: C++17 特性
    - cpp20: C++20 特性
    - cpp23: C++23 特性
    - all: 查看所有标准概览
    """
    resource = get_standards_resource()

    if version == "all":
        return resource.get_all_standards()

    return resource.get_standard_features(version)


@mcp.resource("cpp-style://examples/{pattern}")
def get_design_pattern(pattern: str) -> str:
    """
    获取 C++ 设计模式示例

    可用的模式:
    - singleton: 单例模式
    - factory: 工厂模式
    - observer: 观察者模式
    - raii: RAII 惯用法
    - pimpl: Pimpl 惯用法
    - strategy: 策略模式
    - all: 查看所有模式
    """
    resource = get_patterns_resource()

    if pattern == "all":
        return resource.get_all_patterns()

    return resource.get_pattern_example(pattern)


# ==================== Prompts ====================

@mcp.prompt()
def code_review(focus: str = "general") -> str:
    """
    生成 C++ 代码审查提示模板

    参数:
        focus: 审查重点，可选值:
              - general: 综合审查（默认）
              - performance: 性能优化
              - safety: 内存和类型安全
              - readability: 可读性和维护性
              - modern: 现代 C++ 特性使用
    """
    prompt_generator = get_code_review_prompt()
    return prompt_generator.generate(focus)


@mcp.prompt()
def refactor_suggestion(target_standard: str = "cpp17") -> str:
    """
    生成代码重构建议提示模板

    参数:
        target_standard: 目标 C++ 标准
                        - cpp11: C++11
                        - cpp14: C++14
                        - cpp17: C++17
                        - cpp20: C++20
                        - cpp23: C++23
    """
    prompt_generator = get_refactor_prompt()
    return prompt_generator.generate(target_standard)


# 启动服务器（仅在直接运行时）
if __name__ == "__main__":
    # 从环境变量检测运行模式，默认为 stdio
    # Smithery 部署时使用 streamable-http，本地开发使用 stdio
    transport = os.environ.get("MCP_TRANSPORT", "stdio")

    if transport == "streamable-http":
        # HTTP 模式：使用 uvicorn 手动启动以支持 PORT 环境变量
        import uvicorn

        port = int(os.environ.get("PORT", "8000"))

        # 获取 FastMCP 的 streamable HTTP 应用（已包含 /health 自定义路由）
        app = mcp.streamable_http_app()

        # 启动服务器
        uvicorn.run(app, host="0.0.0.0", port=port)
    else:
        # stdio 模式：使用标准方式启动
        mcp.run(transport=transport)