MCP Sandbox Sub Agent

上下文中继MCP服务器

一个模型上下文协议（MCP）服务器，它使AI助手能够查询并处理存储在云存储中的Markdown文档，并利用大型语言模型（LLM）进行分析处理。

概述

Context Relay MCP 是一个基于 FastMCP 的服务器，它连接了人工智能助手与云端存储的文档，使它们能够：

• 列出并发现云存储中的Markdown文档。
• 使用各种大型语言模型（LLM）提供商（OpenAI、Azure OpenAI、Anthropic）根据自定义提示查询文档
• 以可配置的速率限制并发处理多个文档
• 应用来自云端存储提示模板的系统指令

主要特点

• 多云支持与Azure Blob存储配合使用。已包含AWS S3和Google Cloud Storage的样板代码，但尚未完全实现。
• 多语言大模型支持兼容OpenAI、Azure OpenAI和Anthropic Claude
• 安全认证使用存储在云密钥保险库中的秘密进行承载者令牌认证
• 并发处理高效并行处理多个文档
• 系统指令从云存储加载自定义提示模板
• 结构化回应返回包含文档路径和大型语言模型（LLM）响应的结构化JSON
• 全面日志记录详细日志记录，支持可配置的日志级别和文件输出

建筑学

基于提供者的架构

这个项目遵循一个 基于提供者的架构模式 这使得跨不同云平台具备灵活性和可扩展性。 注： 只有Azure已经完成了全面实施和测试。AWS和GCS提供商目前仅包含了样板代码。 该架构由三个主要的提供者层组成：

1. 存储服务提供商 (src/storage/providers/)

- 抽象基类定义了所有存储操作的接口 - 针对Azure Blob存储、AWS S3和Google Cloud Storage的具体实现 - 基于配置的动态提供者选择的工厂模式 - 无论底层存储平台如何，API始终保持一致

1. “Secret Providers”可以翻译为“秘密供应商”或“隐秘提供者”，具体取决于上下文和语境。如果是指在特定领域或情境下不为公众所知的供应商或服务提供者，那么“秘密供应商”可能更为贴切；如果强调的是提供者的隐秘性或不公开性，那么“隐秘提供者”也是一个合适的翻译 (src/secrets/providers/)

- 用于安全密钥管理的抽象基类 - 针对Azure Key Vault、AWS Secrets Manager和GCP Secret Manager的实现 - 集中式秘密检索，封装了供应商特定逻辑 - 支持API密钥和配置密钥

1. 大型语言模型（LLM）提供商 (src/actions/common/llm_processor.py）

- 用于创建大型语言模型（LLM）处理器的工厂模式 - 支持OpenAI、Azure OpenAI和Anthropic Claude - 在不同大型语言模型（LLM）服务之间提供一致的文档处理接口 - 每个提供商的可配置模型、超时设置和并发设置

这种基于供应商的方法提供了诸多优势：

• 可扩展性易于添加新的云平台或大型语言模型（LLM）服务
• 可维护性特定于提供者的逻辑被隔离和封装
• 灵活性通过配置在不同服务提供商之间切换，无需修改代码
• 可测试性可以轻松创建模拟提供者用于测试
• 一致性在不同实现之间保持统一的接口

快速入门

先决条件

• Python 3.13
• 紫外线 （推荐）- 一个快速的Python包管理器

  # Install uv
  curl -LsSf https://astral.sh/uv/install.sh | sh
  # or on macOS/Linux with Homebrew
  brew install uv

• 已配置存储和密钥的云服务提供商账户（Azure、AWS 或 GCS）
• 大型语言模型（LLM）API密钥（OpenAI、Anthropic或Azure OpenAI）

安装

1. 克隆此存储库：

git clone 
cd mcp-sandbox-sub-agent

1. 安装依赖项：

# With uv (recommended)
uv sync

# or with pip:
pip install -e .

1. 配置环境变量：

cp .env.example .env
# Edit .env with your configuration

运行服务器

# With uv
uv run python app.py

# or with Python directly
python app.py

服务器将在8080端口启动（可通过PORT环境变量进行配置）。

配置

环境变量

创建一个 .env 从模板中提取文件并进行以下配置：

所需的Azure配置

AZURE_KEYVAULT_URL=https://your-keyvault.vault.azure.net/
AZURE_STORAGE_ACCOUNT_NAME=yourstorageaccount
AZURE_STORAGE_CONTAINER=your-documents-container
AZURE_PROMPT_CONTAINER=your-prompts-container

大型语言模型（LLM）配置

DEFAULT_LLM_PROVIDER=openai  # or "azure_openai", "anthropic"
OPENAI_MODEL=gpt-4
ANTHROPIC_MODEL=claude-3-sonnet-20240229

# For Azure OpenAI
AZURE_OPENAI_DEPLOYMENT=your-deployment-name
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com

可选设置

LOG_LEVEL=DEBUG
LLM_CONCURRENCY=15
LLM_TIMEOUT_SECONDS=60
CACHE_TTL_HOURS=1

看 .env.example 以获取完整的配置选项列表。

密钥管理

服务器使用云服务提供商的密钥管理工具（如Azure Key Vault等，若未找到则回退到环境变量）来安全地存储：

• 大型语言模型（LLM）提供商的API密钥
• MCP服务器的身份验证令牌
• 其他敏感配置

所需的密钥：

• mcp-server-auth-key用于MCP认证的承载令牌
• 大型语言模型API密钥（基于您的提供商配置）

可用工具

list_docs（可译为“文档列表”或根据上下文具体翻译为相应的术语，如“文档清单”等）

列出云存储中所有可用的Markdown文档。

参数：

• path_prefix （可选）：按路径前缀过滤文档（例如，“policies/”）

返回值：

[
  {
    "path": "docs/example.md",
    "size": "1.2 KB",
    "last_modified": "2024-01-15T10:30:00Z"
  }
]

查询文档

使用提供的提示，通过大型语言模型（LLM）处理Markdown文档。

参数：

• prompt （必填）：给大型语言模型（LLM）的指令或问题
• document_paths （可选）：要处理的特定文档列表。如果省略，则处理所有Markdown文件。

返回值：

[
  {
    "document_path": "docs/example.md",
    "response": "LLM analysis of the document..."
  }
]

使用示例

列出文件

# List all documents
await mcp.list_docs()

# List documents in a specific folder
await mcp.list_docs(path_prefix="policies/")

查询文档

# Query all documents
await mcp.query_docs(prompt="Summarize the key points")

# Query specific documents
await mcp.query_docs(
    prompt="What are the security requirements?",
    document_paths=["policies/security.md", "policies/compliance.md"]
)

发展

添加新功能

添加新工具

1. 在（指定位置）创建一个新的动作文件 src/actions/：

async def my_tool_action(
    required_param: str,
    storage_provider: StorageProvider,  # Injected
    optional_param: str = "default"
) -> dict:
    """Tool description."""
    # Implementation
    return result

1. 服务器启动时，该工具将自动注册。

添加新的存储提供商

1. 在（系统/环境中）创建一个新的提供者 src/storage/providers/
2. 实施 StorageProvider 基类
3. 更新工厂中的（信息/设置等，具体根据上下文确定） src/storage/factory.py

添加新的大型语言模型（LLM）提供商

1. 在（系统/环境中）创建一个新的处理器 src/actions/common/
2. 实现大型语言模型（LLM）交互逻辑
3. 更新 LLMProcessorFactory 在 llm_processor.py

安全考虑事项

• API密钥永远不要将API密钥或机密提交到版本控制系统中
• 认证在生产环境中始终使用强大且唯一的承载令牌（Bearer tokens）
• 网络对外部通信全部使用HTTPS/TLS
• 秘密将所有敏感数据存储在云密钥管理服务中
• 访问控制为云资源配置适当的IAM角色
• 记录日志确保日志中不包含敏感信息

故障排除

常见问题

1. 存储访问错误验证云存储的IAM角色和权限
2. 秘密访问错误检查密钥库/秘密管理器的权限
3. LLM 超时增加 LLM_TIMEOUT_SECONDS 对于大型文档
4. 速率限制调整 LLM_CONCURRENCY 基于API限制

记录（日志）

启用调试日志以进行故障排除：

LOG_LEVEL=DEBUG
FILE_LOGGING=true
LOGS_DIR=logs