讲座MCP服务器
一个通用的MCP（模型上下文协议）服务器，用于处理PDF中的讲座材料。提取文本，将其分块进行LLM处理，并使用Google Gemini AI在LaTeX支持下转换为干净的Markdown。
🚀 特性
- PDF文本提取：从针对LLM上下文限制进行优化的PDF文件中提取和组块文本
- Markdown转换：使用LaTeX支持将纯文本转换为格式良好的Markdown
- MCP协议：支持SSE（服务器发送事件）和stdio传输
- AI驱动：使用Google Gemini进行智能内容格式化
- 可扩展：易于向注册表添加自定义工具
📋 先决条件
🔧 安装
1.安装uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh2.克隆和设置
# Clone repository
git clone https://github.com/MarinCervinschi/lecture-mcp-server
cd lecture-mcp-server
# Install dependencies
uv sync3.配置API密钥
创建一个 .env 文件：
cp .env.example .env编辑 .env 并添加您的Gemini API密钥：
GEMINI_API_KEY=your_actual_api_key_here🚀 用法
运行服务器
苏格兰和南方能源公司运输（推荐）
uv run python run.py --transport sse服务器将于启动 http://localhost:8000/mcp
这是用于测试和与MCP客户端集成的推荐传输方法。
标准运输
uv run python run.py --transport stdio⚠️ 备注：stdio传输方法尚未完全测试。
测试服务器
1.启动SSE服务器⬆️
2.使用Google ADK Web UI进行测试
在单独的终端中，启动ADK web界面：
adk web --port 8080然后打开浏览器 http://localhost:8080 与使用MCP服务器工具的代理进行交互。
示例代理配置位于 sse_agent/agent.py -这只是一个测试工具，用于验证MCP服务器是否正常工作。
⚙️ 可用的MCP工具
1. pdf_to_text
从PDF和块中提取文本以进行LLM处理。
输入：
file_data（string）：Base64编码的PDF文件内容
输出：
metadata：PDF信息（页面、大小等）total_chunks：创建的块数chunks：包含页码和标记计数的文本块列表
2. text_to_markdown
使用LaTeX支持将纯文本转换为格式良好的Markdown。
输入：
content（字符串）：要转换的纯文本
输出：
markdown：格式化的Markdown内容
3. filter_content
通过去除噪声和无关信息来过滤和清理内容。
输入：
content（string）：要筛选的文本
输出：
filtered_content：已清理和筛选的文本
🧪 测试
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=app --cov-report=html
# Run specific test
uv run pytest tests/mcp_tools/test_pdf_to_text.py🔨 发展
添加新工具
要向MCP服务器添加自定义工具，请执行以下操作：
1.创建工具类
在中创建新文件 应用程序/工具/ （例如。， my_new_tool.py):
from typing import Any, Dict
from mcp.types import Tool as MCPTool
from pydantic import BaseModel, Field
from app.tools.base import BaseMCPTool
class MyToolArgs(BaseModel):
"""Input schema for the tool"""
input_param: str = Field(..., description="Description of the parameter")
class MyToolResult(BaseModel):
"""Output schema for the tool"""
result: str = Field(..., description="Description of the result")
class MyNewTool(BaseMCPTool):
"""Description of what your tool does."""
def _create_schema(self) -> MCPTool:
"""Create tool schema for MCP."""
return MCPTool(
name="my_new_tool",
description="What this tool does",
inputSchema=MyToolArgs.model_json_schema(),
outputSchema=MyToolResult.model_json_schema(),
)
async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
"""Execute the tool logic."""
validated_params = MyToolArgs(**args)
# Your tool logic here
result = MyToolResult(result=f"Processed: {validated_params.input_param}")
return result.model_dump()2.注册工具
打开 app/services/mcp_register.py 并添加您的工具：
from app.tools.my_new_tool import MyNewTool
class MCPToolRegistry:
def _register_default_tools(self) -> None:
"""Register all default tools."""
tools: List[Tool] = [
PDFToTextTool(),
TextToMarkdownTool(),
MyNewTool(), # Add your tool here
]3.测试你的工具
重新启动服务器，您的工具将通过MCP协议自动可用。
添加依赖关系
# Add production dependency
uv add package-name
# Add development dependency
uv add --dev package-name配置
所有设置都在 app/core/config.py.按键设置：
GEMINI_MODEL：要使用的模型（默认值：gemini-2.5-flash）MAX_CHUNK_SIZE：每个区块的令牌限制（默认值：2000）MAX_FILE_SIZE：最大PDF大小（以字节为单位）（默认值：10MB）HOST/PORT：服务器主机和端口（默认值：0.0.0.0:8000）
代码质量
# Format code
uv run black app/
uv run isort app/
# Lint
uv run ruff check app/
# Type checking
uv run mypy app/📖 其他文件
🤝 贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试和代码质量检查
- 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件