Langchain Agent Mcp Server

LangChain Agent MCP Server

一个可投入生产的 MCP 服务，通过模型上下文协议提供 LangChain Agent 功能，部署在 Google Cloud Run 上。

🚀 概述

这是一个独立的后端服务，将 LangChain Agent 封装为一个高阶 MCP 工具。该服务使用 FastAPI 构建，并部署在 Google Cloud Run 上，为向任何兼容 MCP 的客户端提供 AI Agent 功能提供可扩展、可投入生产的解决方案。

在线服务： https://langchain-agent-mcp-server-554655392699.us-central1.run.app

✨ 功能

• ✅ 符合 MCP 规范 - 全面支持模型上下文协议
• ✅ LangChain Agent - 使用 ReAct 模式进行多步推理
• ✅ Playwright 沙盒 - 无障碍快照的交互式预览（新功能！）
• ✅ Google Cloud Run - 可扩展的无服务器部署
• ✅ 工具支持 - 可扩展的自定义工具框架
• ✅ 可投入生产 - 错误处理、日志记录和监控
• ✅ Docker 支持 - 容器化，便于部署

🏗️ 架构

组件	技术	用途
后端框架	FastAPI	高性能异步 Web 服务
Agent 框架	LangChain	多步推理和工具执行
部署	Google Cloud Run	无服务器、自动扩缩的托管服务
容器化	Docker	一致的部署环境
协议	模型上下文协议（MCP）	标准化的工具和上下文共享

🛠️ 快速开始

前置条件

• Python 3.11+
• OpenAI API 密钥
• Google Cloud 账号（用于部署到 Cloud Run）
• Docker（可选，用于本地测试）

本地开发

1. 克隆代码库：

   git clone https://github.com/mcpmessenger/LangchainMCP.git
   cd LangchainMCP
   

2. 安装依赖项：

   # Windows
   py -m pip install -r requirements.txt
   
   # Linux/Mac
   pip install -r requirements.txt
   

3. 设置环境变量： 创建一个 .env 文件：

   OPENAI_API_KEY=your-openai-api-key-here
   OPENAI_MODEL=gpt-4o-mini
   PORT=8000
   

4. 运行服务：

   # Windows
   py run_server.py
   
   # Linux/Mac
   python run_server.py
   

5. 测试端点：

   • 健康状态：http://localhost:8000/health
   • 清单：http://localhost:8000/mcp/manifest
   • API 文档：http://localhost:8000/docs
   • Playwright 沙盒：http://localhost:8080/sandbox（启动前端后）

6. 启动前端（可选）：

   # Install frontend dependencies (first time only)
   npm install
   
   # Start frontend dev server
   npm run dev
   

   然后访问 http://localhost:8080/sandbox，使用 Playwright 沙盒预览功能。

☁️ 部署到 Google Cloud Run

该服务专为部署到 Google Cloud Run 而设计。请参阅我们的完整部署指南：

• DEPLOY_CLOUD_RUN_WINDOWS.md - Windows 部署指南
• DEPLOY_CLOUD_RUN.md - 通用部署指南
• QUICK_DEPLOY.md - 快速参考

快速部署

# Windows PowerShell
.\deploy-cloud-run.ps1 -ProjectId "your-project-id" -Region "us-central1"

# Linux/Mac
./deploy-cloud-run.sh your-project-id us-central1

当前部署

• 服务 URL： https://langchain-agent-mcp-server-554655392699.us-central1.run.app
• 项目： slashmcp
• 区域： us-central1
• 状态： ✅ 在线运行

📡 API 端点

MCP 端点

获取清单

GET /mcp/manifest

返回声明可用工具的 MCP 清单。

响应：

{
  "name": "langchain-agent-mcp-server",
  "version": "1.0.0",
  "tools": [
    {
      "name": "agent_executor",
      "description": "Execute a complex, multi-step reasoning task...",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "The user's query or task"
          },
          "system_instruction": {
            "type": "string",
            "description": "Optional system-level instructions to customize agent behavior"
          }
        },
        "required": ["query"]
      }
    }
  ]
}

调用工具

POST /mcp/invoke
Content-Type: application/json

{
  "tool": "agent_executor",
  "arguments": {
    "query": "What is the capital of France?",
    "task_id": "optional-workflow-id"
  }
}

使用系统指令（可选）：

POST /mcp/invoke
Content-Type: application/json

{
  "tool": "agent_executor",
  "arguments": {
    "query": "Analyze Tesla stock",
    "system_instruction": "You are a financial analyst. Provide detailed analysis with specific numbers."
  }
}

响应：

{
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "isError": false
}

系统指令

agent_executor 工具支持可选的 system_instruction 参数，可按每次调用自定义 Agent 的行为。

用法：

• 基本查询（使用默认提示词）：

  {
    "tool": "agent_executor",
    "arguments": {
      "query": "What is the weather today?"
    }
  }
  

• 带自定义指令的查询：

  {
    "tool": "agent_executor",
    "arguments": {
      "query": "Explain quantum computing",
      "system_instruction": "You are a physics professor. Explain concepts clearly and use examples."
    }
  }
  

• 个性化设置：

  {
    "tool": "agent_executor",
    "arguments": {
      "query": "Tell me about space",
      "system_instruction": "You are a pirate explaining complex topics. Use pirate terminology!"
    }
  }
  

注意：

• 如果省略 system_instruction，Agent 将使用默认提示词
• 空指令或仅包含空白字符的指令会被忽略（使用默认提示词）
• 每次使用自定义指令调用时，都会创建一个新的 Agent 实例

Playwright 沙盒端点

生成无障碍快照

POST /api/playwright/snapshot
Content-Type: application/json

{
  "url": "wikipedia.org",
  "use_cache": true
}

响应：

{
  "snapshot": "[body]\n  Name: Wikipedia\n  [main]\n    Name: Main content...",
  "url": "https://wikipedia.org",
  "cached": false,
  "token_count": 3307
}

功能：

• 生成任意网站的结构化无障碍快照
• 展示 AI 如何通过结构化数据“查看”网站
• 支持缓存热门网站
• 估算 token 数量
• 兼容 Windows（使用 ProactorEventLoop）

对照快照测试提示词

POST /api/playwright/test-prompt
Content-Type: application/json

{
  "snapshot": "[body]\n  [button]\n    Name: Login",
  "prompt": "Find the login button"
}

响应：

{
  "matches": [
    {
      "line": 2,
      "content": "[button] Name: Login",
      "context": "..."
    }
  ],
  "prompt": "Find the login button",
  "total_matches": 1
}

Playwright 沙盒 UI： 访问 http://localhost:8080/sandbox 使用交互式预览功能：

• 输入任意 URL 以生成快照
• 并排查看实时网站与 AI 无障碍快照
• 测试提示词以在快照中查找元素
• 查看与完整 HTML/截图相比节省的 token 数量

其他端点

• GET / - 服务信息
• GET /health - 健康检查
• GET /api/tasks - 安全的任务摘要（可选监控）
• GET /api/tasks/{task_id} - 安全的任务摘要（可选监控）
• GET /docs - 交互式 API 文档（Swagger UI）

🔧 配置

环境变量

变量	描述	默认值	必填
OPENAI_API_KEY	OpenAI API 密钥	-	✅ 是
OPENAI_MODEL	要使用的 OpenAI 模型	gpt-4o-mini	否
PORT	服务端口	8000	否
API_KEY	用于身份验证的可选 API 密钥	-	否
MAX_ITERATIONS	Agent 最大迭代次数	10	否
DEFAULT_SYSTEM_INSTRUCTION	默认系统提示词（Glazyr）	-	否
VERBOSE	启用详细日志记录	false	否
POLICY_ENFORCEMENT	强制执行 /mcp/invoke 策略门控	false	否
MAX_QUERY_CHARS	允许的最大查询长度	5000000	否
ALLOWLISTED_DOMAINS	以逗号分隔的域名允许列表（查询 URL）	-	否
REDIS_URL	启用 Redis 状态存储和任务监控	-	否
TASK_TTL_SECONDS	任务摘要的 TTL	86400	否
RECENT_TASKS_MAX	最近任务索引大小	200	否

📚 文档

📖 完整文档站点 - 包含示例的完整文档（GitHub Pages）

快速链接：

• 快速入门 - 在本地设置并运行
• 示例 - 代码示例，包括 “用 10 行代码构建 RAG Agent”
• 部署指南 - 部署到 Google Cloud Run
• API 参考 - 完整的 API 文档
• 故障排除 - 常见问题及解决方案

在本地构建文档：

# Windows
.\build-docs.ps1 serve

# Linux/Mac
./build-docs.sh serve

其他指南：

• README_BACKEND.md - 完整技术文档
• PLAYWRIGHT_SANDBOX_SETUP.md - Playwright 沙盒设置与使用
• BUG_REPORT_PLAYWRIGHT_NOTIMPLEMENTEDERROR.md - Windows 兼容性修复文档
• DEPLOY_CLOUD_RUN_WINDOWS.md - Windows 部署指南
• INSTALL_PREREQUISITES.md - 安装先决条件
• SLASHMCP_INTEGRATION.md - SlashMCP 集成指南
• docs/glazyr-integration.md - Glazyr 集成说明（截图 → MCP invoke）

🧪 测试

# Test health endpoint
Invoke-WebRequest -Uri "https://langchain-agent-mcp-server-554655392699.us-central1.run.app/health"

# Test agent invocation
$body = @{
    tool = "agent_executor"
    arguments = @{
        query = "What is 2+2?"
    }
} | ConvertTo-Json

Invoke-WebRequest -Uri "https://langchain-agent-mcp-server-554655392699.us-central1.run.app/mcp/invoke" `
    -Method POST `
    -ContentType "application/json" `
    -Body $body

# Test with system instruction
$bodyWithInstruction = @{
    tool = "agent_executor"
    arguments = @{
        query = "What is 2+2?"
        system_instruction = "You are a math teacher. Explain your reasoning step by step."
    }
} | ConvertTo-Json

Invoke-WebRequest -Uri "https://langchain-agent-mcp-server-554655392699.us-central1.run.app/mcp/invoke" `
    -Method POST `
    -ContentType "application/json" `
    -Body $bodyWithInstruction

🎭 Playwright 沙盒功能

Playwright 沙盒是一项交互式预览功能，展示 AI Agent 如何通过结构化无障碍数据“查看”网站。这项功能尤其适用于了解结构化快照相较于完整 HTML 或屏幕截图的价值。

功能

• 双视图界面：并排查看实时网站及其结构化无障碍快照
• Token 效率：比较 Token 数量——快照通常比完整 HTML 小 90% 以上
• 交互式测试：测试提示词，以便在快照中查找元素
• 缓存：缓存热门网站，加快演示速度
• 兼容 Windows：使用 ProactorEventLoop 修复了 Windows 上的 NotImplementedError

快速开始

1. 安装 Playwright：

   py -m pip install playwright
   py -m playwright install chromium
   

2. 启动后端：

   py run_server.py
   

3. 启动前端：

   npm install  # First time only
   npm run dev
   

4. 访问沙盒： 打开 http://localhost:8080/sandbox 并尝试以下 URL：

   • wikipedia.org
   • github.com
   • google.com

工作原理

1. 输入 URL - 系统使用 Playwright 访问网站
2. 生成快照 - 提取结构化无障碍信息（角色、名称、描述）
3. 查看对比 - 查看实时网站与 AI 的结构化视图
4. 测试提示词 - 尝试让 AI 查找特定元素

技术详情

• 后端：集成 Playwright 的 FastAPI 端点
• 前端：使用 TanStack Query 的 React + Vite
• 事件循环：在 Windows 上使用 ProactorEventLoop，以支持子进程
• 隐身模式：采取反机器人检测措施，以提高兼容性
• 错误处理：妥善处理会阻止自动访问的网站

详细设置说明请参阅 PLAYWRIGHT_SANDBOX_SETUP.md。

🏗️ 项目结构

.
├── src/
│   ├── main.py              # FastAPI application with MCP endpoints
│   ├── agent.py             # LangChain agent definition and tools
│   ├── pages/
│   │   └── Sandbox.tsx      # Playwright Sandbox UI component
│   ├── mcp_manifest.json    # MCP manifest configuration
│   └── start.sh             # Cloud Run startup script
├── tests/
│   └── test_mcp_endpoints.py # Test suite
├── Dockerfile               # Container configuration
├── requirements.txt         # Python dependencies (includes playwright)
├── deploy-cloud-run.ps1     # Windows deployment script
├── deploy-cloud-run.sh      # Linux/Mac deployment script
└── cloudbuild.yaml          # Cloud Build configuration

🚀 部署选项

Google Cloud Run（推荐）

• 可扩展 - 根据流量自动扩缩容
• 无服务器 - 只为实际使用量付费
• 托管式 - 无需管理基础设施
• 快速 - 通过全球 CDN 实现低延迟

详细说明请参阅 DEPLOY_CLOUD_RUN_WINDOWS.md。

Docker（本地／其他平台）

docker build -t langchain-agent-mcp-server .
docker run -p 8000:8000 -e OPENAI_API_KEY=your-key langchain-agent-mcp-server

📊 性能

• **P95 延迟：**标准的 3 步 ReAct 链低于 5 秒
• **可扩展性：**在 Cloud Run 上进行水平扩展
• **正常运行时间：**目标为 99.9%（Cloud Run SLA）
• **吞吐量：**高效处理并发请求

🔒 安全

• API 密钥身份验证（可选）
• 环境变量管理
• Secret Manager 集成（Cloud Run）
• 默认启用 HTTPS（Cloud Run）
• CORS 配置

🤝 参与贡献

欢迎贡献！请参阅我们的贡献指南。

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 提交拉取请求

📜 许可证

本项目采用 MIT License 授权。

🔗 链接

• **GitHub 仓库：**https://github.com/mcpmessenger/LangchainMCP
• **在线服务：**https://langchain-agent-mcp-server-554655392699.us-central1.run.app
• **API 文档：**https://langchain-agent-mcp-server-554655392699.us-central1.run.app/docs
• **Model Context Protocol：**https://modelcontextprotocol.io/

🙏 致谢

• 使用 LangChain 构建
• 部署于 Google Cloud Run
• 使用 FastAPI 作为 Web 框架

---

状态：✅ 已投入生产并部署于 Google Cloud Run