上下文中继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提供商目前仅包含了样板代码。 该架构由三个主要的提供者层组成：
- 存储服务提供商 (
src/storage/providers/)
- 抽象基类定义了所有存储操作的接口 - 针对Azure Blob存储、AWS S3和Google Cloud Storage的具体实现 - 基于配置的动态提供者选择的工厂模式 - 无论底层存储平台如何，API始终保持一致
- “Secret Providers”可以翻译为“秘密供应商”或“隐秘提供者”，具体取决于上下文和语境。如果是指在特定领域或情境下不为公众所知的供应商或服务提供者，那么“秘密供应商”可能更为贴切；如果强调的是提供者的隐秘性或不公开性，那么“隐秘提供者”也是一个合适的翻译 (
src/secrets/providers/)
- 用于安全密钥管理的抽象基类 - 针对Azure Key Vault、AWS Secrets Manager和GCP Secret Manager的实现 - 集中式秘密检索，封装了供应商特定逻辑 - 支持API密钥和配置密钥
- 大型语言模型（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）
安装
- 克隆此存储库：
git clone
cd mcp-sandbox-sub-agent- 安装依赖项：
# With uv (recommended)
uv sync
# or with pip:
pip install -e .- 配置环境变量：
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"]
)发展
添加新功能
添加新工具
- 在（指定位置）创建一个新的动作文件
src/actions/：
async def my_tool_action(
required_param: str,
storage_provider: StorageProvider, # Injected
optional_param: str = "default"
) -> dict:
"""Tool description."""
# Implementation
return result- 服务器启动时，该工具将自动注册。
添加新的存储提供商
- 在（系统/环境中）创建一个新的提供者
src/storage/providers/ - 实施
StorageProvider基类 - 更新工厂中的（信息/设置等，具体根据上下文确定）
src/storage/factory.py
添加新的大型语言模型（LLM）提供商
- 在（系统/环境中）创建一个新的处理器
src/actions/common/ - 实现大型语言模型（LLM）交互逻辑
- 更新
LLMProcessorFactory在llm_processor.py
安全考虑事项
- API密钥永远不要将API密钥或机密提交到版本控制系统中
- 认证在生产环境中始终使用强大且唯一的承载令牌（Bearer tokens）
- 网络对外部通信全部使用HTTPS/TLS
- 秘密将所有敏感数据存储在云密钥管理服务中
- 访问控制为云资源配置适当的IAM角色
- 记录日志确保日志中不包含敏感信息
故障排除
常见问题
- 存储访问错误验证云存储的IAM角色和权限
- 秘密访问错误检查密钥库/秘密管理器的权限
- LLM 超时增加
LLM_TIMEOUT_SECONDS对于大型文档 - 速率限制调整
LLM_CONCURRENCY基于API限制
记录（日志）
启用调试日志以进行故障排除：
LOG_LEVEL=DEBUG
FILE_LOGGING=true
LOGS_DIR=logs