AI导哈

MCP服务器开发与诊断工具

MCP Architect 是一套面向 Model Context Protocol (MCP) 服务器的专业指南与诊断工具集，提供创建、配置、故障排查和管理 MCP 服务器所需的文档模板、自动化检测脚本及真实案例。

  • by joelaugx
  • Shell
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 joelaugx/Antigravity-MCP-Architect-Skill

使用说明

MCP Architect

Expert guide for creating, configuring, troubleshooting, and managing MCP (Model Context Protocol) servers

🎯 Why This Exists

Antigravity has excellent MCP marketplace integration, but creating custom MCPs is challenging due to:

  • ❌ Sparse documentation on MCP creation
  • ❌ Cryptic error messages
  • ❌ No troubleshooting guides
  • ❌ Complex authentication setup
  • ❌ No diagnostic tools

This skill solves these problems with real-world examples from actual troubleshooting sessions.

✨ What's Included

📚 Comprehensive Documentation

  • SKILL.md: Complete guide (10.8 KB) covering:
    • Common issues & solutions
    • Configuration patterns
    • Python & Node.js templates
    • Testing strategies
    • Best practices

🔧 Diagnostic Tools

  • diagnostic.sh: Automated testing script that:
    • ✅ Validates JSON configuration
    • ✅ Checks if commands exist
    • ✅ Verifies npm packages
    • ✅ Tests Python scripts and venvs
    • ✅ Validates environment variables

💡 Real-World Examples

  • examples/README.md: Based on actual troubleshooting:
    • Google Drive MCP (OAuth authentication)
    • Apple Mail MCP (Python virtual environment)
    • GitHub MCP (Docker container)
    • Master registry pattern

🚀 Quick Start

Use as Antigravity Skill

# Reference the skill when working with MCPs
@mcp-architect I need to create a new MCP for Slack
@mcp-architect My Google Drive MCP is not working
@mcp-architect How do I configure OAuth for an MCP?

Use Diagnostic Tool

# Test your MCP configuration
./examples/diagnostic.sh /path/to/mcp_config.json

Create a New MCP

  1. Choose a template from SKILL.md (Python or Node.js)
  2. Implement your service integration
  3. Test with the diagnostic script
  4. Add to your configuration

📖 Documentation

🎓 Common Use Cases

Troubleshooting a Broken MCP

# Run diagnostic
./examples/diagnostic.sh ~/.gemini/antigravity/mcp_config.json

# Check common issues in SKILL.md
# Apply the fix
# Verify with testing checklist

Creating a Custom MCP

See templates in SKILL.md:

  • Python MCP template (async implementation)
  • Node.js MCP template (TypeScript-based)

Managing Multiple MCPs

Use the master registry pattern from examples/README.md to manage MCPs across multiple tools.

🔑 Key Learnings

Based on real troubleshooting experience:

  1. ✅ Always use absolute paths - Relative paths cause issues
  2. ✅ Verify package names - Check npm/PyPI before configuring
  3. ✅ Use dedicated venvs - Isolate Python MCP dependencies
  4. ✅ Environment variables for credentials - Never hardcode secrets
  5. ✅ Test manually first - Verify MCPs work before adding to config
  6. ✅ Validate JSON - Use jq to catch syntax errors
  7. ✅ Document authentication - OAuth flows need clear instructions
  8. ✅ Master registry pattern - Manage MCPs across multiple tools

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Ways to contribute:

  • 🐛 Report issues you've encountered
  • 💡 Share your MCP examples
  • 📝 Improve documentation
  • 🔧 Enhance diagnostic tools

📜 License

MIT License - See LICENSE.txt for details

🙏 Acknowledgments

Created from real-world experience troubleshooting MCPs for:

  • Google Drive (OAuth authentication)
  • Apple Mail (Python venv setup)
  • Apple Photos (Python implementation)
  • Brave Search (API key management)
  • CloudRun (GCP integration)
  • GitHub (Docker container)
  • Google Docs (Python venv)
  • File Systems (Node.js)

📞 Support

  • 📖 Read the SKILL.md documentation
  • 🔍 Check examples/README.md for real-world cases
  • 🐛 Open an issue for bugs or questions
  • 💬 Start a discussion for general questions

Made with ❤️ to help the MCP community

相关 MCP