使用说明
MCP浏览器
一个现代的全栈应用程序，用于探索模型上下文协议（MCP）服务器并与之交互。MCP Explorer提供了一个用户友好的界面，可以连接到MCP服务器，发现可用的工具，并使用自定义参数执行它们。
🚀 特性
- 轻松连接MCP服务器：通过STDIO协议连接到任何MCP服务器
- 工具发现：自动列出连接服务器中的所有可用工具
- 交互式工具执行：使用自定义参数执行工具并查看结果
- 实时状态监控：实时监控连接状态
- 现代用户界面：使用Next.js和React构建，提供流畅的用户体验
- REST API：用于编程访问的全面REST API
- Docker支持：使用Docker Compose轻松部署
- CORS已启用：跨源请求的完全CORS支持
📋 目录
🏗️ 建筑
MCP Explorer遵循 分层架构 明确区分关注点：
┌─────────────────────────────────────────────────┐
│ Next.js Frontend (React) │
│ (Port 3000) │
└─────────────────┬───────────────────────────────┘
│ HTTP Requests
│
┌─────────────────▼───────────────────────────────┐
│ FastAPI Backend (Python) │
│ (Port 8000) │
└─────────────────┬───────────────────────────────┘
│
┌─────────┴──────────┐
│ │
┌───────▼────────┐ ┌──────▼──────────┐
│ MCP Clients │ │ Connection │
│ (STDIO) │ │ Manager │
└────────────────┘ └─────────────────┘
│
└─────────────────────┬─────────────────┐
│ │
┌───────▼────────┐ ┌────▼──────────┐
│ MCP Server 1 │ │ MCP Server 2 │
└────────────────┘ └───────────────┘
有关详细的体系结构信息，请参见 后端/ARCHITECTURE.md.
🛠️ 技术栈
后端
- Python 3.13+：现代Python运行时
- 快速API：高性能web框架
- Uvicorn：ASGI服务器
- 派丹蒂克：数据验证
- MCP-SDK（1.25.0+）：官方模型上下文协议库
前端
- Next.js：带有服务器端渲染的React框架
- 反应18：UI库
- TypeScript：类型安全的JavaScript
- Tailwind CSS：实用程序优先的CSS框架
- Radix UI：无头UI组件库
- React钩子形式：灵活的表单处理
开发运维
- 码头工人：集装箱化
- Docker Compose：多容器编排
- 拉夫：Python linter和格式化程序
📦 先决条件
- 码头工人: 安装 Docker
- Docker Compose: 安装Docker Compose
或手动设置：
- Python 3.13+
- Node.js 18+
- npm 或 pnpm
🐳 Docker Compose快速入门
1.克隆存储库
git clone https://github.com/yourusername/mcp-explorer.git
cd mcp-explorer
2.启动应用程序
docker-compose up -d
这将开始：
- 前端：可在http://localhost:3000
- 后端API：可在http://localhost:8000
3.验证服务是否正在运行
docker-compose ps
您应该看到：
NAME STATUS
mcp-explorer-frontend Up
mcp-explorer-backend Up
4.访问应用程序
- 网络界面：打开http://localhost:3000在浏览器中
- API 文档：参观http://localhost:8000/docs
5.停止应用程序
docker-compose down
要同时删除卷，请执行以下操作：
docker-compose down -v
🔧 手动设置
后端设置
-
导航到后端目录:
cd backend -
创建虚拟环境 （可选但推荐）：
python3.13 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate -
安装依赖项:
pip install -e . -
运行开发服务器:
python main.py或者直接与Uvicorn合作：
uvicorn main:app --reload --host 0.0.0.0 --port 8000
后端将在 http://localhost:8000
前端设置
-
导航到前端目录:
cd frontend -
安装依赖项:
npm install # or pnpm install -
运行开发服务器:
npm run dev # or pnpm dev前端将在
http://localhost:3000
📁 项目结构
mcp-explorer/
├── backend/ # Python FastAPI application
│ ├── main.py # Application entry point
│ ├── pyproject.toml # Python dependencies
│ ├── Dockerfile # Backend container config
│ ├── ARCHITECTURE.md # Detailed architecture docs
│ │
│ └── src/
│ ├── factory.py # FastAPI app factory
│ ├── lifespan.py # App lifecycle events
│ ├── exceptions.py # Global exceptions
│ │
│ ├── api/ # API layer
│ │ ├── dependencies.py # FastAPI dependencies
│ │ ├── schemas.py # Request/response models
│ │ └── endpoints/
│ │ └── stdio.py # STDIO connection endpoints
│ │
│ ├── mcp/ # MCP integration
│ │ ├── manager.py # Connection manager
│ │ ├── exceptions.py # MCP-specific exceptions
│ │ ├── client/ # MCP client implementations
│ │ │ ├── base.py # IMCPClient protocol
│ │ │ ├── stdio.py # STDIO client
│ │ │ └── http.py # HTTP client (planned)
│ │ └── connection/ # Connection models
│ │ ├── connection.py
│ │ ├── config.py
│ │ └── type.py
│ │
│ └── utils/ # Utilities
│ └── logging/
│
├── frontend/ # Next.js React application
│ ├── package.json # Node dependencies
│ ├── Dockerfile # Frontend container config
│ ├── next.config.mjs # Next.js configuration
│ ├── tsconfig.json # TypeScript config
│ │
│ ├── app/ # Next.js app directory
│ │ ├── layout.tsx # Root layout
│ │ ├── page.tsx # Home page
│ │ └── globals.css # Global styles
│ │
│ ├── components/ # React components
│ │ ├── mcp-explorer.tsx # Main explorer component
│ │ ├── connection-sidebar.tsx
│ │ ├── tools-panel.tsx
│ │ ├── results-panel.tsx
│ │ └── ui/ # Radix UI components
│ │
│ ├── hooks/ # Custom React hooks
│ │ └── use-mcp-connection.ts # MCP connection hook
│ │
│ ├── lib/ # Utilities
│ │ ├── types.ts # TypeScript types
│ │ └── utils.ts # Helper functions
│ │
│ └── public/ # Static assets
│
├── test-server/ # Example MCP test server
│ ├── main.py
│ ├── tools.py
│ └── pyproject.toml
│
├── docker-compose.yml # Docker Compose configuration
└── README.md # This file
📡 API终点
根
GET /-API信息
MCP STDIO操作
| 方法 | 端点 | 描述 |
|---|---|---|
POST |
/mcp/stdio/connect |
连接到MCP服务器 |
POST |
/mcp/stdio/disconnect |
断开与服务器的连接 |
GET |
/mcp/stdio/status |
获取连接状态 |
GET |
/mcp/stdio/list-tools |
列出可用工具 |
POST |
/mcp/stdio/execute |
执行工具 |
文档
GET /docs-Swagger用户界面（交互式）GET /redoc-重新记录文档GET /openapi.json-OpenAPI模式
💻 前端使用
连接到MCP服务器
-
打开http://localhost:3000
-
使用连接侧边栏创建新连接
-
提供服务器详细信息：
- 名字：连接标识符
- 命令：可执行文件（例如。，
python) - 参数：命令参数（例如。，
-m my_mcp_server) - 环境：可选环境变量
-
点击“连接”
执行工具
- 连接后，可用工具将显示在工具面板中
- 选择一个工具以查看其输入模式
- 填写所需参数
- 点击“执行”
- 在结果面板中查看结果
🚀 发展
后端开发
-
启动开发服务器:
cd backend python main.py -
运行linter/格式化程序:
ruff check . ruff format . -
访问API文档: http://localhost:8000/docs
前端开发
-
启动开发服务器:
cd frontend npm run dev -
为生产而建:
npm run build -
运行门楣:
npm run lint
代码质量
该项目执行代码质量标准：
后端（Ruff）:
- 行长：79个字符（PEP 8）
- 目标：Python 3.13
- 启用的规则：pycodestyle、pyflakes、pep8命名、pydocstyle、pyupgrade、isort、flake8 bugbear、flake9推导、flake10简化
🐛 故障排除
容器无法启动
# Check logs
docker-compose logs
# Rebuild containers
docker-compose build --no-cache
# Start again
docker-compose up
后端连接错误
确保后端正在运行且可访问：
curl http://localhost:8000/
前端无法连接到后端
- 验证后端是否正在运行：
http://localhost:8000 - 检查中的CORS设置
backend/src/factory.py - 确保两个服务都在同一个Docker网络上
MCP服务器连接问题
- 验证MCP服务器命令是否正确
- 在结果面板中检查服务器日志
- 确保安装了所有必需的依赖项
端口冲突
如果端口3000或8000正在使用中：
选项1：停止使用这些端口的其他服务
lsof -i :3000 # Check port 3000
lsof -i :8000 # Check port 8000
选项2：修改 docker-compose.yml:
services:
frontend:
ports:
- "3001:3000" # Changed to 3001
backend:
ports:
- "8001:8000" # Changed to 8001
📚 其他资源
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🤝 贡献
欢迎投稿！请随时提交拉取请求。
💡 未来的增强功能
- []连接持久性和历史
- []身份验证和授权
- []HTTP/SSE MCP客户端支持
- []连接池
- []性能指标和监控
- []工具执行模板
- []结果导出功能
快乐探索！ 🚀
