Frontend Geo MCP

前端GPS🚀

React项目的导航员和代码审查员

MCP（模型上下文协议）服务器，对GitHub存储库中的React组件进行索引，并通过Cursor AI提供智能搜索和导航功能。

✨ 特性

• 🔍 组件搜索：按名称在多个项目中查找React组件
• 📚 JSDoc文件：提取和搜索组件文档
• 📦 道具和钩子检测：自动提取组件道具和React钩子
• 🏢 多项目支持：同时对多个存储库进行索引和搜索
• 🔄 自动同步：从GitHub克隆和索引存储库
• 💾 PostgreSQL后端：使用SQLAlchemy ORM的快速可靠的组件数据库
• 🚀 MCP集成：与Cursor AI的原生集成
• 📝 版本控制：使用Alembic进行数据库迁移

📋 需求

• Python 3.12+
• Docker桌面（用于本地PostgreSQL）
• 紫外线 包管理器
• Git

📦 技术栈

• FastMCP 2.13.0+ -MCP服务器框架
• SQLAlchemy 2.0+ -ORM用于数据库操作
• Pydantic 2.0+ -数据验证
• 蒸馏器 -数据库迁移
• PostgreSQL 15 -数据库引擎
• Python 3.12 -运行时间

📁 项目结构

frontend-geo-mcp/
├── src/
│   ├── server.py              # MCP Server entry point
│   ├── models.py              # SQLAlchemy + Pydantic models
│   ├── tools/
│   │   ├── navigator.py       # Component search and navigation
│   │   ├── validator.py       # Code validation tools
│   │   └── guide.py           # Project guidance
│   ├── registry/
│   │   └── database_client.py # Database ORM client
│   └── utils/
│       ├── indexer.py         # Repository indexing
│       ├── parser.py          # React component parser
│       └── cache.py           # Caching system
├── scripts/
│   ├── setup_local_db.sh      # Database initialization
│   ├── test_local_db.py       # Connection test
│   ├── sync_projects.py       # Manual project sync
│   └── explore_db.py          # Database explorer
├── migrations/                # Alembic database migrations
├── docs/                      # Documentation
├── pyproject.toml             # Python dependencies
├── docker-compose.yml         # Docker services
└── Dockerfile                 # Production Docker image

🚀 快速开始

1.克隆和安装

git clone https://github.com/your-org/frontend-geo-mcp
cd frontend-geo-mcp
uv sync

2.设置数据库

chmod +x scripts/setup_local_db.sh
./scripts/setup_local_db.sh

这将启动PostgreSQL，应用迁移，并创建必要的表。

3.配置和测试

# Copy environment template
cp config.env.example .env

# Test database connection
uv run python scripts/test_local_db.py

4.配置项目

编辑 .mcp-config.json 使用您的存储库：

{
  "projects": {
    "my-app": {
      "repository": "https://github.com/user/my-app",
      "branch": "main",
      "type": "application"
    }
  }
}

5.同步和运行

# Sync projects
uv run python scripts/sync_projects.py --all

# Start MCP server
fastmcp dev src/server.py:mcp

有关详细的设置说明，请参阅 📖 设置.md

______________________________________________________________________

📚 MCP工具

搜索工具

• find_component -按名称查找组件
• search_by_hook -使用特定钩子查找组件
• search_by_jsdoc -搜索组件文档

详细工具

• get_component_details -获取组件元数据
• get_component_docs -获取完整的JSDoc文档

浏览工具

• list_components -列出所有索引组件
• list_projects -显示所有已配置的项目

管理工具

• sync_project -手动同步项目
• get_stats -查看索引统计信息

有关完整的工具参考，请参阅 📖 工具文档

______________________________________________________________________

🗄️ 数据库管理

Web UI（管理员）

http://localhost:8080

CLI访问

docker exec -it frontend-mcp-db psql -U postgres -d frontend_mcp

有关数据库迁移和详细管理，请参阅 📖 设置.md

______________________________________________________________________

🐳 码头工人

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f postgres

______________________________________________________________________

🚢 部署

铁路/渲染

# Set DATABASE_URL environment variable
uv run python src/server.py --http

Docker构建

docker build -t frontend-geo-mcp:latest .
docker run -e DATABASE_URL=... frontend-geo-mcp:latest

______________________________________________________________________

📖 文档

完整的指南可在 /docs:

______________________________________________________________________

🛠️ 发展

测试

# Instalar dependencias de desarrollo (solo primera vez)
uv sync --dev
# o
make install-dev

# Ejecutar todas las pruebas
uv run pytest
# o usar el script
./scripts/test.sh
# o usar make
make test

# Ejecutar pruebas con cobertura
uv run pytest --cov=src --cov-report=html
# o
make test-cov

# Ejecutar pruebas específicas
uv run pytest tests/test_tools.py
uv run pytest tests/test_repositories.py

# Ejecutar solo tests unitarios (excluir integration)
uv run pytest -m "not integration"
# o
make test-unit

# Ver ayuda de comandos make
make help

# Test database connection
uv run python scripts/test_local_db.py

# Explore database interactively
uv run python scripts/explore_db.py

# Test MCP tools with visual inspector
fastmcp inspect src/server.py:mcp

关键文件

• src/models.py -SQLAlchemy模型
• src/registry/database_client.py -数据库客户端
• src/tools/navigator.py -搜索工具
• src/server.py -FastMCP服务器

______________________________________________________________________

🐛 故障排除

______________________________________________________________________

📝 环境变量

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/frontend_mcp
TEMP_DIR=/tmp/mcp-repos
API_KEY=local-dev-key
GITHUB_TOKEN=          # Optional
PORT=8080

看 设置.md 详细配置。

______________________________________________________________________

📞 支持

• 检查 安装指南
• 查看 架构指南
• 请参阅 数据库引用
• 打开一个包含详细信息的GitHub问题