MCP Audit Server

审计平台

用于存储库审计的干净微服务架构。

建筑

audit-platform/
├── core/                    # Brain - Rules & Workflows
│   ├── workflows/          # YAML workflow definitions
│   ├── rules/              # Scoring rules
│   ├── knowledge/          # Metrics knowledge base
│   └── engine.py           # Workflow orchestrator
├── executors/              # Hands - Execution modules
│   ├── git-analyzer/       # Git operations
│   ├── static-analyzer/    # Code analysis
│   ├── security-scanner/   # Security scanning
│   ├── llm-reviewer/       # LLM-based review
│   └── report-generator/   # Report generation
├── gateway/                # API Layer
│   ├── mcp/               # MCP server for Claude
│   └── api/               # REST API for web
└── ui/                    # Web interface

快速开始

1.安装依赖项

pip install -r requirements.txt

2.配置环境

export INFRA_ENV_PATH=/Users/maksymdemchenko/AI-Platform-ISO-main/infrastructure/.env
# Optional overrides:
export DATABASE_URL=postgres://user:pass@localhost:5432/audit
export REDIS_URL=redis://localhost:6379

3.运行MCP HTTP服务器

python -m gateway.mcp.http_server
# UI and MCP server available at http://localhost:8090

4.运行API（可选）

python -m gateway.api.main
# API available at http://localhost:8080

5.运行CLI审核（可选）

python -m run --source /path/to/repo --task quick_scan

文档

• docs/GETTING_STARTED.md -完整设置和使用
• docs/ESTIMATION_FORMULAS.md -固定公式及其使用地点
• docs/MCP_WEB_SERVER.md -MCP服务器详细信息和UI

与克劳德（MCP）一起使用

添加到您的Claude配置中：

{
  "mcpServers": {
    "audit-platform": {
      "command": "python",
      "args": ["-m", "gateway.mcp.server"],
      "cwd": "/path/to/audit-platform"
    }
  }
}

然后在克劳德：

• “审核存储库https://github.com/user/repo"
• “解释repo_health评分的含义”
• “这个项目是什么级别的，如何改进？”

安全配置（推荐）

为生产部署设置以下环境变量：

• REQUIRE_AUTH=true 以在MCP和API端点上实施承载令牌认证。
• MCP_AUTH_TOKENS=token1,token2 定义允许的静态令牌。
• OAUTH_ALLOWED_CLIENT_IDS=... 只允许已知的OAuth客户端ID。
• OAUTH_REDIRECT_DOMAINS=claude.ai,app.claude.ai 限制重定向主机。
• ALLOWED_ORIGINS=https://claude.ai,https://app.claude.ai,https://seh.foundation 对于CORS。
• ALLOWED_REPO_HOSTS=github.com,gitlab.com 限制回购克隆。
• MCP_WORKSPACE_ROOT=/tmp/mcp_workspaces 分离克隆的repos。
• ENABLE_DANGEROUS_TOOLS=false 禁用 run_script, run_tests, check_lint, check_types, find_duplicates.
• MCP_TOOL_POLICY=production|internal|dev 控制安全工具与特权工具。
• STRICT_ESTIMATION=true 对估计值实施验证界限。
• RATE_MIN, RATE_MAX, HOURS_PER_KLOC_MIN, HOURS_PER_KLOC_MAX 以覆盖验证边界。

工具策略层：

• production：仅限安全工具
• internal：安全+特权工具
• dev：所有工具（仍被阻止 ENABLE_DANGEROUS_TOOLS=false 除非明确启用）

危险工具（默认禁用）：

• run_script, run_tests, check_lint, check_types, find_duplicates

特权工具（需要 MCP_TOOL_POLICY=internal 或 dev):

• clone_repo, analyze_repo, scan_security, analyze_complexity, generate_report, export_results, batch_analyze
• upload_document, upload_document_file, get_document, delete_document
• update_settings, load_results, list_policies

重命名工具：

• upload_document_file （基于file_path的上传）。这取代了旧的 upload_document 文件工具名称。

可用工具（MCP）

请参阅：

• TOOLS.md （策略层级）
• docs/MCP_WEB_SERVER.md （HTTP MCP服务器使用情况）

报告分块

这 generate_report 该工具支持对大输出进行分块：

{
  "name": "generate_report",
  "arguments": {
    "analysis_id": "abc123",
    "sections": ["summary", "metrics", "estimation"],
    "format": "markdown",
    "chunking": { "mode": "by_size", "max_chars": 20000 }
  }
}

评分

存储库运行状况（0-12）

• 自述文件（+2）
• 许可证（+1）
• 测试（+2）
• CI/CD（+2）
• Docker（+1）
• 主动提交（+2）
• 多个贡献者（+2）

技术债务（0-15）

• 低复杂度（+3）
• 低重复（+3）
• 皮棉问题很少（+3）
• 更新的依赖关系（+3）
• 良好的测试覆盖率（+3）

产品级别

API终点

REST API（端口8080）

GET  /health                    # Health check
GET  /api/workflows             # List workflows
POST /api/audit                 # Start audit
GET  /api/audit/{id}            # Get status
GET  /api/audit/{id}/report     # Get report
WS   /api/ws/audit/{id}         # Progress updates
POST /api/explain/metric        # Explain metric
GET  /api/explain/level/{name}  # Explain level
POST /api/recommendations       # Get recommendations