Loist MCP服务器

基于FastMCP的服务器，用于音频摄取和嵌入音乐库MCP协议。

概述

该项目使用FastMCP框架实现了一个模型上下文协议（MCP）服务器，用于管理音乐库系统的音频文件摄取、处理和嵌入生成。

建筑亮点

该服务器具有现代、可扩展的架构，具有：

仓储模式：通过依赖注入实现干净的数据访问抽象
统一异常框架：具有自动恢复策略的全面错误处理
高级元数据提取：ID3标签、BWF元数据、XMP数据、智能文件名解析和编辑器→艺术家回退
性能优化：通过批处理，数据库操作速度提高了75-80%
全面测试：85%以上的测试覆盖率，自动性能验证
Clean FastMCP集成：零异常序列化解决方法
生产就绪：针对云运行进行了优化，具有连接池和运行状况监控功能

MCP服务器命名策略

该项目支持 2个不同的环境 本地开发和云测试/生产之间有明确的分离：

本地开发：Docker容器的快速迭代
暂存：基于云的集成测试和质量保证
生产：实时生产部署

每个环境都有不同的命名约定，以避免MCP客户端配置中的冲突：

本地开发

光标MCP服务器名称: loist-music-library-local
FastMCP服务器名称: Music Library MCP - Local Development
环境：具有本地PostgreSQL+GCS集成的Docker容器
运输：stdio（用于Cursor MCP集成）

预发布环境

光标MCP服务器名称: loist-music-library-staging
FastMCP服务器名称: Music Library MCP - Staging
环境：使用PostgreSQL+专用GCS暂存桶进行云运行
运输：http/sse（用于集成测试和QA）
部署：启用云构建触发器 dev 分支机构(cloudbuild-staging.yaml)
目的：预生产验证、集成测试、QA验证
基础设施：独立的云运行服务、临时GCS存储桶、临时数据库

生产部署

光标MCP服务器名称: loist-music-library （生产）
FastMCP服务器名称: Music Library MCP - Production
环境：GCloud基础设施（云SQL+GCS）
运输：可配置（stdio/http/sse）

谷歌云平台

📚 完整的谷歌云平台概述 -所有GCP服务和基础设施的全面指南。

基础设施概述

该系统基于Google Cloud Platform构建，采用现代无服务器架构：

┌─────────────────────────────────────────────────────────────┐
│                    Google Cloud Platform                    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐ │
│  │ Cloud Build │───▶│  Artifact    │───▶│   Cloud Run     │ │
│  │   CI/CD     │    │  Registry    │    │ (Serverless)    │ │
│  └─────────────┘    └──────────────┘    └─────────────────┘ │
│                                                ▲             │
│  ┌─────────────┐    ┌──────────────┐         │             │
│  │   Cloud     │    │    Secret    │         │             │
│  │    SQL      │◀───┤   Manager    │◀────────┘             │
│  │(PostgreSQL) │    │              │                       │
│  └─────────────┘    └──────────────┘                       │
│                                                             │
│  ┌─────────────┐    ┌──────────────┐                       │
│  │   Cloud     │    │     IAM      │                       │
│  │  Storage    │◀───┤  SignBlob    │◀──────────────────────┘
│  │   (GCS)     │    │    API       │
│  └─────────────┘    └──────────────┘
└─────────────────────────────────────────────────────────────┘

关键基础设施组件：

云运行：具有自动扩展功能的无服务器容器平台
云SQL：使用连接池管理PostgreSQL
云存储：通过IAM SignBlob生成签名URL的对象存储
云构建：具有漏洞扫描功能的自动化CI/CD
秘密经理：安全的凭证和配置管理
工件注册表：容器图像存储和管理
身份和访问管理：用于安全GCS访问的服务帐户模拟

应用架构

服务器实现了一个分层架构，明确分离了关注点：

┌─────────────────┐
│   FastMCP       │  ← Protocol Layer (MCP v1.16.0)
│   Protocol      │
├─────────────────┤
│ Business Logic  │  ← Service Layer (Repository Pattern)
│ Repository      │
├─────────────────┤
│ Data Access     │  ← Persistence Layer
│ PostgreSQL      │    (Cloud SQL + GCS)
│ Google Cloud    │
│ Storage         │
└─────────────────┘

协议和API访问

服务器提供了两种主要的交互方法：用于核心工具的规范MCP JSON-RPC协议和用于操作监控和便利包装的标准HTTP端点。

有关设计理念的详细说明，请参阅新 MCP服务器架构文件。

标准协议：MCP JSON-RPC

与服务器核心业务逻辑交互的规范和推荐方式是通过 MCP JSON-RPC协议。这是为代理工作流和编程工具使用而设计的。通信通过配置的传输（stdio、HTTP或SSE）进行。

您通过向服务器发送JSON-RPC 2.0请求来与服务器交互 /mcp 端点（在HTTP/SSE模式下）使用两种主要方法：

tools/list：发现所有可用的核心业务工具。
tools/call：使用参数执行特定工具。

核心业务工具（通过MCP）

以下是通过MCP协议可用的主要工具：

process_audio_complete
get_audio_metadata
update_metadata
delete_audio
search_library
download_audio
get_embed_url

使用示例

这里有一些 curl 通过HTTP与MCP服务器交互的示例。

列出可用工具

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

调用工具： `process_audio_complete`

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"process_audio_complete",
      "arguments":{"source":{"type":"http_url","url":"https://example.com/track.mp3"}}
    }
  }'

调用工具： `search_library`

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"search_library",
      "arguments":{"query":"rock"}
    }
  }'

操作和REST端点（仅限HTTP）

对于操作监控和简单的基于REST的访问，服务器公开了标准的HTTP端点。这些是不 MCP工具，应直接访问。

操作端点

GET /health/ready, /health/live：返回服务器的运行状况。对于Cloud Run和其他容器编排平台至关重要。
get_waveform_metrics_tool：提供波形生成的度量。
get_circuit_breaker_status：显示内部断路器的状态。

REST API端点

为了方便起见，特别是对于web前端，提供了一组RESTful端点作为一些MCP工具功能的包装器。

GET /api/tracks/{audioId} -获取跟踪元数据
GET /api/search?q= -使用过滤器搜索曲目
GET /api/tracks/{audioId}/stream -获取已签名的流媒体URL
GET /api/tracks/{audioId}/thumbnail -获取签名缩略图URL

A2A代理对代理协议

服务器实现 A2A（代理对代理）v0.3规范 用于代理发现和任务协调，使其他AI代理能够以编程方式发现此音乐处理服务并与之交互。

代理发现

代理可以通过标准A2A发现端点发现此服务的功能：

# Get agent card with capabilities and skills
curl https://a2a-staging-{PROJECT_ID}.us-central1.run.app/.well-known/agent-card.json

主要特点

代理卡：符合A2A v0.3标准的发现文档，包含6项核心技能
JSON-RPC API：代理间任务协调的标准协议
异步任务处理：带状态轮询的背景音频处理
共享业务逻辑：MCP和A2A接口使用的处理管道相同

核心技能

该代理向其他代理公开这些功能：

process_audio_complete -具有元数据提取功能的完整音频处理
search_library -带过滤器的高级文本搜索
get_audio_metadata -检索完整的曲目元数据
update_metadata -编辑元数据字段
delete_audio -从库中删除曲目
get_embed_url -生成可嵌入的播放器URL

环境端点

暂存: https://a2a-staging-{PROJECT_ID}.us-central1.run.app\ 生产: https://a2a-prod-{PROJECT_ID}.us-central1.run.app

集成指南

📚 完整的A2A集成指南 -分步集成说明、JSON-RPC示例、身份验证详细信息和故障排除。

关键建筑改进

存储库模式实现

清洁数据访问：具有多种实现的抽象接口
依赖注入：具有模拟存储库的可测试代码
演出：优化了批处理操作和连接池

统一异常框架

一致的错误处理：跨所有组件的单一框架
恢复策略：自动重试和断路器模式
FastMCP集成：清除错误序列化，无需解决方法

数据库性能优化

批量操作：批量插入速度提高5倍
智能索引：10+性能指标，实现最佳查询
连接池：针对云运行无服务器进行了优化

综合测试策略

85%+覆盖率：单元、集成和性能测试
数据库测试基础架构：完成迁移、连接池、事务、全文搜索和数据完整性的测试
自动验证：性能回归检测
Docker集成：隔离的测试数据库环境
CI/CD集成：对每次部署进行自动化测试

配置详情

本地开发（.cursor/mcp.json）：

{
  "loist-music-library-local": {
    "command": "python3",
    "args": ["/Users/Gareth/loist-mcp-server/run_server.py"],
    "cwd": "/Users/Gareth/loist-mcp-server",
    "env": {
      "SERVER_TRANSPORT": "stdio",
      "SERVER_NAME": "Music Library MCP - Local Development"
    }
  }
}

生产部署：

{
  "loist-music-library": {
    "command": "python3",
    "args": ["/path/to/production/server.py"],
    "env": {
      "SERVER_NAME": "Music Library MCP - Production"
    }
  }
}

此命名策略允许两个环境在Cursor MCP客户端配置中共存，而不会发生冲突。

开发与测试

开发流程

该项目遵循结构化的开发工作流程，并进行全面的测试：

功能开发：使用Task Master进行任务分解和跟踪
代码实现：遵循存储库模式和异常框架
测试：使用运行全面的测试套件 pytest
性能验证：自动性能回归测试
文档：更新架构更改的技术文档

测试策略

该项目实施了一种具有全面pytest基础设施的多层测试方法。

📚 完整的测试设置指南 -详细的测试文档和设置说明。

快速开始

启动所有服务:

   docker-compose up -d

运行测试 （始终在Docker内部）：

   docker-compose exec mcp-server pytest tests/ -v

⚠️ 重要：始终在Docker中运行测试。当地的venv已经过时了。

测试类别

单元测试: docker-compose exec mcp-server pytest tests/ -m unit -v
集成测试: docker-compose exec mcp-server pytest tests/ -m integration -v
数据库测试: docker-compose exec mcp-server pytest tests/ -m requires_db -v
GCS测试: docker-compose exec mcp-server pytest tests/ -m requires_gcs -v

测试执行

重要：测试运行 Docker内部 具有正确的依赖关系和PYTHONPATH配置。

# All tests
docker-compose exec mcp-server pytest tests/ -v

# Unit tests only (fast, no database)
docker-compose exec mcp-server pytest tests/ -m unit -v

# Integration tests (requires database)
docker-compose exec mcp-server pytest tests/ -m integration -v

# With coverage
docker-compose exec mcp-server pytest tests/ --cov=src --cov-report=term-missing

测试基础设施

85%+覆盖率：综合单元和集成测试
性能测试：自动回归检测
异常测试：统一框架验证
存储库测试：依赖注入和模拟
全文搜索测试：索引验证、查询准确性、性能和相关性测试
自动标记：基于文件/功能模式的自动测试分类

安全扫描

# Run comprehensive security scan
./scripts/security-scan.sh

# Run individual security tools
bandit -r src/ -f json -o reports/bandit-scan.json
safety scan --output json --target .

安全类别

土匪分析：Python安全漏洞扫描
安全检查：依赖性漏洞评估
自定义安全：硬编码的秘密、调试代码、文件权限
基线执行：对高严重性问题零容忍

文档

综合文档可在 docs/ 目录：

架构概述：完整的系统架构
异常处理指南：统一的错误框架
数据库最佳实践：性能优化
模块组织指南：代码结构模式
测试策略：综合测试方法
安全扫描指南：安全基础设施和扫描工具

关键开发命令

# Run full test suite (inside Docker)
docker-compose exec mcp-server pytest tests/ -v

# Run with performance monitoring
docker-compose exec mcp-server pytest tests/ --durations=10

# Run database integration tests
docker-compose exec mcp-server pytest tests/test_database_operations_integration.py -v

# Generate coverage report
docker-compose exec mcp-server pytest tests/ --cov=src --cov-report=term-missing

# Run security scanning
./scripts/security-scan.sh

# Run individual security tools
bandit -r src/
safety scan --target .

先决条件

Python 3.11或更高版本
uv 包管理器（在安装过程中安装）

安装

1.克隆存储库

git clone 
cd loist-mcp-server

2.安装Python 3.11+

macOS（使用Homebrew）：

brew install python@3.11

Linux：

sudo apt-get update
sudo apt-get install python3.11

3.安装uv包管理器

curl -LsSf https://astral.sh/uv/install.sh | sh

添加 uv 到你的路径：

export PATH="$HOME/.local/bin:$PATH"

4.创建虚拟环境

uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

5.安装依赖项

uv pip install -r requirements.txt

或直接安装：

uv pip install fastmcp

项目结构

loist-mcp-server/
├── src/
│   ├── exceptions/         # Unified exception framework
│   │   ├── __init__.py    # Framework exports
│   │   ├── handler.py     # Core exception handler
│   │   ├── context.py     # Exception context system
│   │   ├── recovery.py    # Recovery strategies
│   │   ├── config.py      # Configuration options
│   │   └── fastmcp_integration.py # FastMCP integration
│   │
│   ├── repositories/       # Data access layer
│   │   ├── __init__.py    # Repository exports
│   │   └── audio_repository.py # Audio repository interface & implementations
│   │
│   ├── fastmcp_setup.py   # Clean FastMCP initialization
│   ├── server.py          # MCP server and tool registration
│   ├── config.py          # Application configuration
│   │
│   ├── resources/         # MCP resource handlers
│   │   ├── __init__.py
│   │   ├── metadata.py    # Metadata resource
│   │   ├── audio_stream.py # Audio streaming resource
│   │   └── thumbnail.py   # Thumbnail resource
│   │
│   ├── tools/             # MCP tool implementations
│   │   ├── __init__.py
│   │   ├── process_audio.py # Audio processing tool
│   │   └── query_tools.py # Search and query tools
│   │
│   ├── auth/              # Authentication module
│   │   ├── __init__.py
│   │   └── bearer.py      # Bearer token authentication
│   │
│   └── exceptions.py      # Legacy exception classes (backward compatibility)
│
├── database/              # Database layer
│   ├── __init__.py
│   ├── operations.py      # Database operations
│   ├── pool.py           # Connection pooling
│   ├── config.py         # Database configuration
│   └── migrations/       # Schema migrations
│
├── tests/                 # Comprehensive test suite
│   ├── conftest.py       # Test configuration and fixtures
│   ├── test_*.py         # Unit tests
│   ├── test_*_integration.py # Integration tests
│   └── __pycache__/
│
├── docs/                  # Technical documentation
│   ├── architecture-overview.md      # System architecture
│   ├── exception-handling-guide.md   # Error framework
│   ├── database-best-practices.md    # DB optimizations
│   ├── module-organization-guide.md  # Code structure
│   ├── testing-strategy-and-recovery.md # Testing approach
│   └── [additional docs...]
│
├── scripts/               # Utility scripts
├── tasks/                 # Task Master files
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Project configuration
├── .env.example          # Example environment variables
└── README.md             # This file

运行服务器

开发模式（STDIO）

推荐：使用Docker进行开发 （确保当前的依赖关系）：

# Run server directly
./run_mcp_stdio_docker.sh

替代方案：使用虚拟环境 （可能有过时的依赖关系）：

source .venv/bin/activate  # Activate virtual environment
python src/server.py

使用MCP检查器（stdio）

MCP Inspector为测试工具和资源提供了一个交互式调试界面。

选项A：独立检查员 （推荐）

# 1. Launch MCP Inspector (opens in browser)
npx @modelcontextprotocol/inspector@latest

# 2. In Inspector UI:
#    - Transport: stdio
#    - Command: /Users/Gareth/loist-mcp-server/run_mcp_stdio_docker.sh
#    - Working Directory: /Users/Gareth/loist-mcp-server

选项B：命令行测试

# Test tools and resources via command line
./test_mcp_tools.sh
./test_mcp_resources.sh

在Inspector中测试什么：

健康检查：验证服务器状态和配置
获取音频元数据：使用无效ID进行测试以查看错误处理
搜索库：使用简单查询进行测试（预计stdio模式下会出现数据库错误）
资源：测试 music-library://audio/{id}/metadata|stream|thumbnail URI

HTTP模式（使用CORS嵌入iframe）

在中将传输设置为HTTP .env:

SERVER_TRANSPORT=http
SERVER_PORT=8080
ENABLE_CORS=true

然后运行：

source .venv/bin/activate
python src/server.py

服务器将在 http://localhost:8080/mcp

SSE模式（服务器发送事件）

将传输设置为SSE .env:

SERVER_TRANSPORT=sse
SERVER_PORT=8080

特性

当前实施情况

建筑与设计

✅ 仓储模式：通过依赖注入实现干净的数据访问抽象
✅ 统一异常框架：使用恢复策略进行全面的错误处理
✅ 性能优化：通过批处理，数据库操作速度提高了75-80%
✅ Clean FastMCP集成：零异常序列化解决方法
✅ 分层架构：协议、业务逻辑和数据层之间的明确分离

FastMCP和协议

✅ FastMCP服务器初始化（v2.12.4，MCP v1.16.0）
✅ 使用Pydantic进行高级配置管理
✅ 寿命挂钩（启动/关闭）
✅ 多种传输模式（STDIO、HTTP、SSE）
✅ 工具和资源注册模式

数据库和存储

✅ PostgreSQL与优化的连接池集成
✅ 用于音频文件管理的谷歌云存储
✅ 综合索引策略（10+性能指标）
✅ 具有事务管理的批处理操作
✅ 零停机部署的迁移系统

错误处理和可靠性

✅ 具有自动恢复功能的统一异常框架
✅ 断路器和重试模式
✅ 带上下文的结构化错误响应
✅ 全面的日志记录和性能监控
✅ 健康检查和系统监控

搜索和筛选

✅ 高级全文搜索：带有加权排名的PostgreSQL tsvector
✅ 时间段过滤：相对时段（本周、上周、今天等）
✅ 自定义日期范围：ISO格式日期过滤，支持时区
✅ 多面过滤：XMP元数据（作曲家、出版商、唱片公司）
✅ 分页和排序：基于光标的分页，顺序稳定
✅ 时区感知处理：process_audio_cocomplete中的用户时区支持

音轨管理（完整CRUD）

✅ 创建: process_audio_complete -通过元数据提取从URL中获取音频
✅ 阅读: get_audio_metadata -按ID检索完整的曲目元数据
✅ 更新: update_metadata -使用JSON合并补丁语义进行部分更新
✅ 删除: delete_audio -从库中删除曲目
✅ 搜索: search_library -具有高级过滤功能的全文搜索
✅ 下载：HTTP API+ download_audio MCP工具-实时格式转换（MP3、WAV、FLAC、AAC、OGG），嵌入元数据/艺术作品

安全与配置

✅ 承载令牌身份验证（SimpleBearerAuth）
✅ iframe嵌入的CORS配置
✅ 基于环境的配置管理
✅ 错误消息中的敏感数据屏蔽
✅ 输入验证和净化

测试与质量

✅ 全面的测试套件（覆盖率超过85%）
✅ 自动化性能回归测试
✅ 使用模拟进行存储库模式测试
✅ Docker数据库集成测试
✅ 异常框架验证
✅ 安全扫描基础架构：土匪、安全、海关检查
✅ 安全基线执行：对高严重性问题零容忍

开发经验

✅ 结构化开发的Task Master集成
✅ 全面的文档套件
✅ 类型提示和文档标准
✅ 开发/生产配置文件
✅ 清晰的模块组织，边界清晰

时间段过滤和时区支持

服务器现在支持高级基于时间的过滤，用于按创建日期查找轨迹：

相对时间段

搜索在特定时间段内创建的曲目：

// Find tracks from this week
await search_library({
  "query": "rock music",
  "filters": {
    "time": {"period": "this_week"}
  }
});

// Find tracks from last week
await search_library({
  "query": "jazz",
  "filters": {
    "time": {"period": "last_week"}
  }
});

可用时间段

today -今天创建的曲目
yesterday -昨天创建的曲目
this_week -本周（周一至周日）创建的曲目
last_week -上周创建的曲目
this_month -本月创建的曲目
last_month -上个月创建的曲目
this_year -今年创建的曲目
last_year -去年创建的曲目

自定义日期范围

对于支持时区的精确日期过滤：

await search_library({
  "query": "electronic",
  "filters": {
    "time": {
      "dateFrom": "2025-11-01",
      "dateTo": "2025-11-30",
      "timezone": "America/New_York"
    }
  }
});

用户时区支持

这 process_audio_complete 工具现在接受时区参数：

await process_audio_complete({
  "source": {"type": "http_url", "url": "https://example.com/song.mp3"},
  "options": {
    "timezone": "America/New_York"  // IANA timezone name
  }
});

元数据编辑

这 update_metadata 该工具支持使用JSON合并补丁语义进行部分更新：

// Update specific fields (omitted fields remain unchanged)
await update_metadata({
  "audioId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "artist": "The Beatles",
    "year": 1968,
    "genre": "Rock"
  }
});

可编辑字段：

产品元数据： artist, title, album, genre, year
XMP元数据： composer, publisher, record_label, isrc

元数据处理：

作曲家→艺术家后退：当艺术家字段为空时，作曲家会自动用古典音乐和电影配乐填充艺术家，以获得更好的用户体验

行为：

省略字段→ 保持不变
提供价值→ 更新到新值
数据库触发自动更新 search_vector 和 updated_at

计划的功能

🔄 高级OAuth提供者（GitHub、谷歌等）
🔄 JWT令牌支持
🔄 音频文件摄取工具
🔄 嵌入生成
🔄 Docker容器化
🔄 PostgreSQL集成
🔄 谷歌云存储集成

未来范围

A2A推送通知配置存储迁移

当前状态：A2A Phase 2实现使用自定义 PushConfigStore 类，使用原始SQL管理推送通知配置。

未来增强：迁移到A2A SDK的内置 DatabasePushNotificationConfigStore 其提供：

SQLAlchemy ORM模型（而不是原始SQL）
加密支持通过 cryptography.fernet 用于敏感配置数据
更好地与SDK模式和最佳实践保持一致

状态：当前的自定义实现对于MVP来说是正确的。迁移是增强安全性和SDK一致性的未来改进。

相关文件：请参阅中的存档代码审查 docs/archive/a2a-code-reviews/ 进行详细的实施分析。

码头工人

构建Docker镜像

使用全面的构建和验证脚本：

./scripts/test-container-build.sh

或者使用构建脚本：

./scripts/docker/build.sh

或手动：

docker build -t music-library-mcp:latest .

图像详细信息：

多阶段构建：建筑商（Alpine）→ 运行时（阿尔卑斯山）
基本图像: python:3.11-alpine
尺寸：~180MB（高度优化的多阶段构建）
用户：非根(fastmcpuser UID为1000）
安全：具有最小的攻击面、适当的权限和无状态设计
依赖项：包括 psutil, fastmcp，以及所有必需的库
健康检查：内置健康检查，启动期为30秒，兼容云运行

使用Docker运行

使用run脚本：

./scripts/docker/run.sh

或手动：

docker run --rm -p 8080:8080 \
  -e SERVER_TRANSPORT=http \
  -e LOG_LEVEL=INFO \
  -e AUTH_ENABLED=false \
  music-library-mcp:latest

使用Docker Compose

对于具有热重载功能的本地开发：

docker-compose up

服务：

mcp服务器：端口8080上的FastMCP服务器
Postgres：PostgreSQL（已注释掉，准备进行第2阶段）

云运行部署

该项目包括一个全面的自动化部署管道，使用Google Cloud Build进行漏洞扫描、优化构建和完整的环境变量配置。

自动部署（推荐）

使用中定义的Cloud Build管道 cloudbuild.yaml:

# Trigger automated deployment via Cloud Build triggers
# Push to main/dev branch to automatically trigger deployment
git push origin main  # Production deployment
git push origin dev   # Staging deployment

手动部署（替代方案）

对于手动部署，请使用提供的脚本：

# 1. Create Artifact Registry repository (one-time setup)
./scripts/create-artifact-registry.sh

# 2. Build and push image
docker build -t us-central1-docker.pkg.dev/YOUR_PROJECT/music-library-repo/music-library-mcp:latest .
docker push us-central1-docker.pkg.dev/YOUR_PROJECT/music-library-repo/music-library-mcp:latest

# 3. Deploy to Cloud Run
gcloud run deploy music-library-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT/music-library-repo/music-library-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 2Gi \
  --timeout 600s \
  --set-env-vars-file env-vars.yaml

部署功能

✅ 自动化CI/CD：GitHub触发了云构建部署 main 和 dev 分支
✅ 漏洞扫描：自动图像漏洞检测
✅ 多阶段优化：高山建筑商→ Alpine运行时，安全可靠
✅ 综合环境变量：配置了50多个环境变量
✅ 秘密管理：通过秘密管理器获取数据库和地面军事系统证书
✅ 工件注册表：性能更好的现代容器注册表
✅ 构建优化：层缓存、BuildKit和高性能计算机
✅ 部署验证：部署后验证的自动验证脚本

部署验证

使用全面的验证套件验证部署：

# Run full validation
./scripts/validate-deployment.sh

# Individual component validation
./scripts/test-deployment-triggers.sh  # Cloud Build triggers
./scripts/validate-cloud-run.sh        # Service accessibility
./scripts/validate-database.sh         # Database connectivity
./scripts/validate-gcs.sh              # Storage operations

验证文件:

部署验证指南 -如何运行验证
验证结果 -最新验证状态
故障排除指南 -常见问题
回滚程序 -如何回滚

📚 完整部署文档：参见 docs/cloud-run-deployment.md 有关完整的设置说明、故障排除和配置详细信息。

自定义域和HTTPS配置

对于具有自定义域和自动HTTPS的生产部署：

当前状态：域映射已配置，但因服务就绪问题而受阻
实施：全局外部应用程序负载平衡器（推荐）
SSL证书：Google管理的证书，具有自动配置功能
DNS配置：A/AAAA记录指向负载均衡器IP

📚 自定义域设置指南：参见 docs/custom-domain-mapping-guide.md 用于全面的HTTPS和自定义域实现。

CI/CD管道

📚 谷歌云平台概述 -完整的基础设施和部署指南。

该项目使用 Google Cloud Build独家 适用于所有CI/CD操作。GitHub只是一个触发机制。

部署架构

GitHub (Triggers Only)
    ↓
Google Cloud Build (Full CI/CD)
    ↓
Production/Staging Deployment

管道

生产(`cloudbuild.yaml`)

触发：推到 main 分支

7级管道：测试→ 验证→ 构建→ 部署
严格的质量把关（75%的单位，70%的数据库覆盖率）
阻止故障会阻止部署

分期付款(`cloudbuild-staging.yaml`)

触发：推到 dev 分支

相同的综合管道，放宽了门槛
仅警告故障允许部署
预生产验证环境

主要特点

多阶段Docker构建 带安全扫描
数据库测试 与TestContainers隔离
MCP协议验证 API合规性
静态分析 （黑色，伊索特，我的，flake8，土匪）
文物存储 在谷歌云存储
秘密管理 通过谷歌秘密管理器

文档

云构建设置指南 -初始配置
云构建CI/CD设置 -管道架构
云运行部署 -生产部署
测试实践指南 -测试基础设施

📚 完整文档：

测试实践指南 -全面的测试基础设施和CI/CD
PR前测试指南 -在拉取请求之前进行本地测试
云运行部署 -生产部署详细信息
安全扫描 -安全扫描和漏洞管理
产品路线图 -未来的增强功能和计划中的功能

运行工作流

首选行动 GitHub中的选项卡
选择所需的工作流：

- MCP服务器验证 （在推送/PR上自动运行） - 数据库配置 （人工调度）

对于手动工作流：单击 运行工作流 → 选择行动→ 运行工作流

发展

安装开发依赖项

uv pip install -e ".[dev]"

运行测试

⚠️ 重要：始终在Docker中运行测试。当地的venv已经过时了。

# Start services first
docker-compose up -d

# Run all tests
docker-compose exec mcp-server pytest tests/ -v

# Run tests with coverage report
docker-compose exec mcp-server pytest tests/ --cov=src --cov-report=term-missing

# Run specific test file
docker-compose exec mcp-server pytest tests/test_process_audio_complete.py -v

代码质量与静态分析

该项目使用全面的静态分析工具来保证代码质量：

自动质量检查（推荐）

# Install pre-commit hooks for automated quality checks
pip install pre-commit
pre-commit install

# Run all quality checks on staged files
pre-commit run

# Run all quality checks on all files
pre-commit run --all-files

手动质量检查

代码格式和导入排序

# Install formatting tools
pip install black isort

# Format code with black (100 char line length)
black src/ tests/ database/

# Sort imports with isort (compatible with black)
isort src/ tests/ database/

# Check formatting without making changes
black --check --diff src/ tests/ database/
isort --check-only --diff src/ tests/ database/

棉绒和编码质量

# Install linting tools
pip install flake8 pylint bandit safety

# Fast linting with flake8 (PEP8 + PyFlakes + McCabe)
flake8 src/ tests/ database/

# Comprehensive analysis with pylint
pylint src/ tests/ database/

# Security vulnerability scanning
bandit -r src/ database/

# Dependency vulnerability scanning
safety check

类型检查

# Install type checking tools
pip install mypy

# Run type checking with strict settings
mypy src/ database/

# Run with detailed error codes
mypy src/ database/ --show-error-codes

# Check specific module
mypy src/server.py

配置

配置是通过环境变量使用 src/config.py 使用Pydantic设置的模块。该服务器支持所有功能区域的50多个环境变量。

环境变量

📚 完整的环境变量参考：参见 docs/environment-variables.md 用于全面记录所有环境变量、它们的用途、默认值和配置示例。

创建一个 .env 项目根目录中的文件（请参见 .env.example 供参考）：

# Server Identity
SERVER_NAME="Music Library MCP - Local Development"
SERVER_VERSION="0.1.0"
SERVER_INSTRUCTIONS="Your custom instructions here"

# Server Runtime
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_TRANSPORT=stdio  # Options: stdio, http, sse

# Authentication (future)
BEARER_TOKEN=your-secret-token-here
AUTH_ENABLED=false

# Logging
LOG_LEVEL=INFO    # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=text   # Options: json, text

# MCP Protocol
MCP_PROTOCOL_VERSION=2024-11-05
INCLUDE_FASTMCP_META=true

# Duplicate Handling Policies
ON_DUPLICATE_TOOLS=error      # Options: error, warn, replace, ignore
ON_DUPLICATE_RESOURCES=warn   # Options: error, warn, replace, ignore
ON_DUPLICATE_PROMPTS=replace  # Options: error, warn, replace, ignore

# Performance
MAX_WORKERS=4
REQUEST_TIMEOUT=30

# Feature Flags
ENABLE_CORS=true
CORS_ORIGINS=*
ENABLE_METRICS=false
ENABLE_HEALTHCHECK=true

配置功能

集中式配置：中的所有设置 src/config.py 使用Pydantic
环境变量支持：通过以下方式覆盖任何设置 .env 文件
合理违约：服务器无需配置即可开箱即用
类型安全：Pydantic验证所有配置值
寿命管理：用于资源管理的启动和关闭挂钩
自动部署配置：Cloud Build管道自动配置50多个环境变量
秘密管理：通过Google Secret Manager管理敏感数据（数据库凭据、GCS密钥）
验证脚本: scripts/validate-env-config.sh 确保跨环境的配置一致性

部署特定配置

本地开发：基本配置通过 .env 具有合理默认值的文件
云运行生产：通过配置全面的环境变量 cloudbuild.yaml
Docker Compose：开发和分期的特定环境覆盖
验证：自动化脚本确保所有部署方法的配置一致性

错误处理和记录

服务器实现了全面的错误处理和结构化日志记录，用于调试和监控。

错误处理架构

自定义异常层次结构：

MusicLibraryError -所有错误的基本异常
AudioProcessingError -音频文件处理失败
StorageError -地面军事系统/存储操作故障
ValidationError -输入验证失败
ResourceNotFoundError -缺少资源
TimeoutError -操作超时
AuthenticationError -身份验证失败
RateLimitError -超出费率限制
ExternalServiceError -外部服务故障

错误响应

所有错误都会返回标准化的响应：

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    "additional": "context",
    "if": "available"
  }
}

错误代码：

AUDIO_PROCESSING_FAILED -音频处理错误
STORAGE_ERROR -存储操作失败
VALIDATION_ERROR -输入无效
RESOURCE_NOT_FOUND -资源不存在
TIMEOUT -操作超时
AUTHENTICATION_FAILED -身份验证错误
RATE_LIMIT_EXCEEDED -请求太多
EXTERNAL_SERVICE_ERROR -外部服务不可用
INTERNAL_ERROR -意外的服务器错误

结构化日志记录

日志记录支持文本和JSON格式：

文本格式 （人类可读）：

2025-10-09 11:54:43 - server - INFO - [server.health_check:86] - Health check passed

JSON格式 （结构化）：

{"timestamp":"2025-10-09 11:54:43","logger":"server","level":"INFO","message":"Health check passed","module":"server","function":"health_check","line":86}

通过环境变量进行配置：

LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=text  # text or json

错误处理实用程序

create_error_response(error) -MCP协议格式错误\ log_error(error, context) -具有结构化上下文的日志\ handle_tool_error(error, tool_name, args) -处理工具错误\ handle_resource_error(error, uri) -处理资源错误\ **safe_execute(func, *args)** -执行时捕获错误

实现示例

from exceptions import AudioProcessingError
from error_utils import handle_tool_error

@mcp.tool()
def process_audio(url: str) -> dict:
    try:
        # Process audio
        result = process_audio_file(url)
        return {"success": True, "data": result}
    except AudioProcessingError as e:
        return handle_tool_error(e, "process_audio", {"url": url})

认证

服务器实现了用于安全访问控制的承载令牌身份验证。

启用身份验证

在您的 .env 文件：

AUTH_ENABLED=true
BEARER_TOKEN=your-secret-token-here

重要安全注意事项：

🔒 永远不要将承载令牌提交给版本控制
🔑 使用强随机生成的令牌（至少32个字符）
🔄 在生产中定期轮换代币
📝 安全地存储令牌（例如，使用秘密管理器）

开发模式（无身份验证）

对于本地开发，可以禁用身份验证：

AUTH_ENABLED=false

服务器将在没有身份验证的情况下运行，并记录警告。

使用带有身份验证的服务器

启用身份验证后，所有MCP协议请求都必须在授权标头中包含有效的承载令牌：

Authorization: Bearer your-secret-token-here

身份验证实现

SimpleBearerAuth：MVP实施 src/auth/bearer.py
令牌验证：根据配置值验证承载令牌
访问控制：退货 AccessToken 带有client_id和作用域
日志记录：跟踪身份验证尝试和失败

未来的身份验证计划

JWT令牌支持已过期
OAuth提供商（GitHub、谷歌、微软）
API密钥管理系统
基于角色的访问控制（RBAC）

CORS配置

服务器支持CORS（跨源资源共享）用于iframe嵌入和跨源请求。

启用CORS

默认情况下，HTTP和SSE传输启用CORS。通过环境变量进行配置：

# CORS Configuration
ENABLE_CORS=true
CORS_ORIGINS=*  # Development: allow all
CORS_ALLOW_CREDENTIALS=true
CORS_ALLOW_METHODS=GET,POST,OPTIONS
CORS_ALLOW_HEADERS=Authorization,Content-Type,Range,X-Requested-With,Accept,Origin
CORS_EXPOSE_HEADERS=Content-Range,Accept-Ranges,Content-Length,Content-Type

生产CORS设置

⚠️ 安全警告： 从不使用 CORS_ORIGINS=* 随着 CORS_ALLOW_CREDENTIALS=true 生产中！

对于生产，请指定确切的来源：

CORS_ORIGINS=https://www.notion.so,https://app.slack.com,https://discord.com

CORS标头说明

允许标头 -客户端可以发送的标头：

Authorization -承载令牌身份验证
Content-Type -请求内容类型
Range -用于音频搜索/流媒体
X-Requested-With, Accept, Origin -标准CORS标头

暴露头 -Headers客户端可以读取：

Content-Range -用于查找的字节范围信息
Accept-Ranges -服务器支持范围请求
Content-Length -进度跟踪的文件大小
Content-Type -响应内容类型

针对不同用例的CORS

Iframe嵌入（概念、松弛、不一致）：

CORS_ORIGINS=https://www.notion.so,https://app.slack.com,https://discord.com
CORS_ALLOW_CREDENTIALS=true

带范围请求的音频流：

CORS_ALLOW_HEADERS=Range,Authorization,Content-Type
CORS_EXPOSE_HEADERS=Content-Range,Accept-Ranges,Content-Length

开发（本地测试）：

CORS_ORIGINS=http://localhost:3000,http://localhost:8000

测试CORS

使用curl测试CORS：

curl -i -H "Origin: https://www.notion.so" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Authorization,Content-Type" \
     -X OPTIONS http://localhost:8080/mcp

应该看到标题：

Access-Control-Allow-Origin: https://www.notion.so
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, Range, ...

多用户SaaS支持

数据库架构包括 user_id 列中 audio_tracks 表支持多用户SaaS功能。每个用户都可以拥有自己的音轨集合，并进行适当的数据隔离。

数据库架构：

user_id INTEGER 列添加到 audio_tracks 桌子
最初为null（在实现用户表时将成为必需）
针对用户特定查询的优化索引
计划用于未来用户的外键关系表

贡献

从以下位置创建要素分支 main
进行更改
运行测试和梳理
提交拉取请求

版本历史

0.1.0 （当前）-使用FastMCP框架进行初始项目设置

许可证

\[待添加许可证信息\]

支持

有关问题和疑问，请在项目存储库上打开问题。

Loist MCP Server

快速接入

详细介绍

Loist MCP服务器

概述

建筑亮点

MCP服务器命名策略

本地开发

预发布环境

生产部署

谷歌云平台

基础设施概述

应用架构

协议和API访问

标准协议：MCP JSON-RPC

核心业务工具（通过MCP）

使用示例

列出可用工具

调用工具： process_audio_complete

调用工具： search_library

操作和REST端点（仅限HTTP）

操作端点

REST API端点

A2A代理对代理协议

代理发现

主要特点

核心技能

环境端点

集成指南

关键建筑改进

存储库模式实现

统一异常框架

数据库性能优化

综合测试策略

配置详情

开发与测试

开发流程

测试策略

快速开始

测试类别

测试执行

测试基础设施

安全扫描

安全类别

文档

关键开发命令

先决条件

安装

1.克隆存储库

2.安装Python 3.11+

3.安装uv包管理器

4.创建虚拟环境

5.安装依赖项

项目结构

运行服务器

开发模式（STDIO）

使用MCP检查器（stdio）

HTTP模式（使用CORS嵌入iframe）

SSE模式（服务器发送事件）

特性

当前实施情况

建筑与设计

FastMCP和协议

数据库和存储

错误处理和可靠性

搜索和筛选

音轨管理（完整CRUD）

安全与配置

测试与质量

开发经验

时间段过滤和时区支持

相对时间段

可用时间段

自定义日期范围

用户时区支持

元数据编辑

计划的功能

未来范围

A2A推送通知配置存储迁移

码头工人

调用工具： `process_audio_complete`

调用工具： `search_library`

生产(`cloudbuild.yaml`)

分期付款(`cloudbuild-staging.yaml`)