使用说明

MCP 学习资源库

一个全面的学习资源库 模型上下文协议（MCP） 概念，展示了从简单工具到复杂代理工作流的实际应用实例。

🎯 学习目标

这个仓库通过逐步构建复杂示例，帮助您理解MCP：

基本MCP概念 - 服务器、工具、资源、提示
工具开发 - 输入验证、错误处理、结构化日志记录
多功能工具集成 - 将工具整合到单一服务器中
大型语言模型（LLM）集成 - 通过Ollama使用本地模型（无需API密钥）
代理工作流 - 为复杂任务协调工具

🚀 快速入门

Python 实现

先决条件

Python 3.11+
Ollama（注：这是一个专有名词，通常指代某个特定的技术、项目或品牌，直接翻译为“奥拉玛”可能无法准确传达其含义，因此在中文中通常保留原名或根据上下文进行解释性翻译。）已安装并运行
至少有一个可用的模型（例如。， qwen3:8b， llama3.2:latest)

设置

# Clone and setup
git clone <repository-url>
cd mcp-learn
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Configure environment (optional)
cp .env.example .env
# Edit .env to customize Ollama settings

验证设置

# Check Ollama is running
ollama list

# Test basic server
python src/examples/simple-server/main.py

Java 实现

先决条件

Java 21（长期支持版）
Gradle 8.0+ 或您选择的构建工具
Ollama（注：这是一个专有名词或特定项目名称，直接翻译可能无法准确传达其含义，因此在此保留原样。）已安装并运行（针对大型语言模型示例）

设置

# Clone and navigate to Java implementation
git clone <repository-url>
cd mcp-learn/java

# Configure environment (optional)
cp env.example .env
# Edit .env to customize settings

# Build the project
./gradlew build

验证设置

# Run simple server example
./gradlew :examples:simple-server:bootRun

# Or run specific examples
./gradlew :examples:multi-tool:bootRun
./gradlew :examples:multi-llm:bootRun
./gradlew :examples:agentic:bootRun

📚 学习路径

第一阶段：基础

目标了解基本的MCP服务器和工具概念

# Simple echo server - demonstrates basic MCP patterns
python src/examples/simple-server/main.py

关键概念服务器初始化、工具注册、输入验证、结构化日志记录

第二阶段：多工具集成

目标学会在一个服务器中整合多种工具

# Multi-tool server - combines echo + math tools
python src/examples/multi-tool/main.py

关键概念工具构成、验证模式、错误处理

第三阶段：大型语言模型（LLM）集成

目标集成本地大型语言模型进行文本生成

# Multi-LLM server - adds Ollama integration
python src/examples/multi-llm/main.py

关键概念大型语言模型（LLM）客户端、模型选择、超时处理、提示工程

第四阶段：代理工作流

目标构建多步骤工作流，将工具串联在一起

# Agentic workflow server - orchestrates complex tasks
python src/examples/agentic/main.py

关键概念工作流编排、提示模板、工具链、状态管理

🛠️ 项目结构

mcp-learn/
├── src/mcp/                    # Core MCP implementation
│   ├── lib/                    # Shared utilities
│   │   ├── config.py          # Environment configuration
│   │   ├── logging.py         # Structured logging setup
│   │   └── validation.py      # Input validation helpers
│   ├── schemas/               # Pydantic models
│   │   └── __init__.py        # Tool input/output schemas
│   ├── servers/               # MCP server implementations
│   │   ├── base.py            # Base server class
│   │   └── agents/            # Agentic workflow components
│   │       └── orchestrator.py
│   ├── tools/                 # Tool implementations
│   │   ├── echo.py            # Simple echo tool
│   │   ├── math.py            # Integer math operations
│   │   └── llm_complete.py    # LLM completion tool
│   ├── services/              # External service integrations
│   │   └── llms/              # LLM service clients
│   │       ├── ollama_client.py
│   │       └── factory.py
│   └── prompts/               # Prompt templates
│       └── templates.py       # Reusable prompt patterns
├── src/examples/              # Runnable examples
│   ├── simple-server/         # Basic MCP server
│   ├── multi-tool/           # Multi-tool integration
│   ├── multi-llm/            # LLM integration
│   └── agentic/              # Agentic workflows
├── specs/001-learn-mcp/      # Specification documents
│   ├── contracts/            # API contracts and schemas
│   ├── plan.md              # Implementation plan
│   └── tasks.md             # Detailed task breakdown
└── requirements.txt          # Python dependencies

🔧 可用工具

工具	用途	输入	输出	示例
`echo`	文本回响着验证信息	`text: str`	回声文本	简单的确定性行为
`sum_ints` 带范围检查的整数加法 `a: int, b: int`	总和结果	带验证的数学运算
`llm_complete`	大语言模型文本生成	`prompt: str, model?: str`	生成的文本	人工智能驱动的回复

🤖 大语言模型（LLM）集成

Ollama 设置

# Install Ollama (if not already installed)
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve

# Pull required models
ollama pull qwen3:8b
ollama pull llama3.2:latest

配置

环境变量（.env 文件)：

# Ollama settings
OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=qwen3:8b

# Logging and timeouts
LOG_LEVEL=INFO
REQUEST_TIMEOUT=30
LLM_TIMEOUT=60

🔄 工作流模式

简单模式：计划 → 执行 → 总结

workflow = [
    WorkflowStep("plan", "llm_complete", 
                {"prompt": "Create a plan for: {task}"}, 
                "Generate task plan"),
    WorkflowStep("execute", "sum_ints", 
                {"a": 42, "b": 8}, 
                "Perform calculation"),
    WorkflowStep("summarize", "llm_complete", 
                {"prompt": "Summarize results for: {task}"}, 
                "Create summary")
]

多功能工具链模式

workflow = [
    WorkflowStep("start", "echo", {"text": "Starting workflow"}, "Begin"),
    WorkflowStep("calculate", "sum_ints", {"a": 123, "b": 456}, "Math"),
    WorkflowStep("explain", "llm_complete", {"prompt": "Explain 123+456"}, "AI Analysis"),
    WorkflowStep("finish", "echo", {"text": "Workflow complete"}, "End")
]

📊 日志记录与可观测性

所有组件均使用结构化JSON日志记录：

{
  "timestamp": "2025-01-01T12:00:00Z",
  "level": "INFO", 
  "logger": "mcp-server",
  "message": "Tool call successful",
  "tool": "sum_ints",
  "inputs": {"a": 5, "b": 3},
  "outputs": {"success": true, "sum": 8}
}

关键日志事件：

server_init - 服务器启动
tool_registered - 工具注册
workflow_start - 工作流执行开始
workflow_step_success - 单个步骤完成
llm_complete_success - 大语言模型（LLM）生成完成

🧪 测试与验证

手动测试

每个示例都包含全面的演示：

# Test individual components
python src/examples/simple-server/main.py    # Basic functionality
python src/examples/multi-tool/main.py       # Tool integration  
python src/examples/multi-llm/main.py        # LLM integration
python src/examples/agentic/main.py          # Workflow orchestration

验证特性

输入验证 通过 Pydantic 模式
范围检查 对于数值输入
超时保护 用于大型语言模型（LLM）调用
错误容错性 在工作流程中
类型安全 在整个代码库中

📖 文档

API 合同 - 详细的工具和工作流程规范
实施计划 - 技术架构和决策
任务分解 - 开发任务详情

🎓 主要学习成果

浏览完这个仓库后，你将了解：

MCP建筑事务所 - 服务器、工具、资源和提示如何协同工作
工具开发 - 创建稳健、经过验证、可观察的工具
大型语言模型（LLM）集成 - 连接本地模型，无需外部依赖
工作流编排 - 构建复杂的多步骤流程
生产模式 - 日志记录、错误处理、超时管理
代码质量 - 验证、类型安全、结构化设计

🔗 下一步行动

扩展工具 - 添加文件操作、API调用、数据库交互
高级工作流 - 实现条件分支，并行执行
资源管理 - 添加MCP资源以访问数据
生产部署 - 添加监控、指标、健康检查
整合 - 连接外部系统和API

🤝 贡献（或“参与贡献”）

这是一个学习资料库。请随意：

尝试这些示例
添加新工具和工作流程
完善文档
分享学习心得

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

快乐学习！ 🚀 从简单的服务器示例开始，逐步深入到复杂的智能代理工作流。

使用说明

MCP 学习资源库

🎯 学习目标

🚀 快速入门

Python 实现

先决条件

设置

验证设置

Java 实现

先决条件

设置

验证设置

📚 学习路径

第一阶段：基础

第二阶段：多工具集成

第三阶段：大型语言模型（LLM）集成

第四阶段：代理工作流

🛠️ 项目结构

🔧 可用工具

🤖 大语言模型（LLM）集成

Ollama 设置

配置

🔄 工作流模式

简单模式：计划 → 执行 → 总结

多功能工具链模式

📊 日志记录与可观测性

🧪 测试与验证

手动测试

验证特性

📖 文档

🎓 主要学习成果

🔗 下一步行动

🤝 贡献（或“参与贡献”）

📄 许可证

相关 MCP

网页内容抓取服务器

模型上下文协议服务器

结构化推理工具

AutoRAG 检索 MCP 服务

Genkit MCP 集成插件

模型上下文协议服务器