使用说明

Gemini工作流桥MCP

Gemini作为上下文压缩引擎+Claude作为推理引擎=A级结果

概述

此MCP是 上下文压缩引擎 这最佳地利用了Claude Code和Gemini的优势。

主要特点

✅ 质量： A级规格（双子座提供事实，克劳德进行推理）
✅ 成本： Claude代币减少47-61%（昂贵的操作转移到免费的Gemini层）
✅ 压缩： 174:1令牌压缩比（50K令牌→ 300 令牌摘要）
✅ DX： 自动生成的工作流和常用任务的斜线命令

建筑

┌─────────────────────────────────────────┐
│   Claude Code (Reasoning Engine)        │
│   - Superior planning & specifications  │
│   - Precise code editing                │
│   - A-grade output quality              │
└──────────────┬──────────────────────────┘
               │ MCP Protocol
               ↓
┌─────────────────────────────────────────┐
│   MCP Server (Compression Layer)        │
│   - 50K tokens → 300 token summaries    │
│   - Fact extraction only                │
│   - Validation & consistency checks     │
└──────────────┬──────────────────────────┘
               │ Gemini CLI
               ↓
┌─────────────────────────────────────────┐
│   Gemini (Context Engine)               │
│   - 2M token window (free tier)         │
│   - Factual extraction only             │
│   - No opinions or planning             │
└─────────────────────────────────────────┘

安装

先决条件

Gemini CLI -安装并验证：

npm install -g @google/gemini-cli
gemini  # Follow authentication prompts

Python 3.11+ 使用pip

安装MCP服务器

# Clone the repository
git clone https://github.com/hitoshura25/gemini-workflow-bridge-mcp
cd gemini-workflow-bridge-mcp

# Install dependencies
pip install -e .

配置Claude代码

添加到您的Claude Code MCP设置中（通常 claude_desktop_config.json):

{
  "mcpServers": {
    "gemini-workflow-bridge": {
      "command": "python",
      "args": ["-m", "hitoshura25_gemini_workflow_bridge"],
      "env": {
        "CONTEXT_CACHE_TTL_MINUTES": "30",
        "MAX_TOKENS_PER_ANSWER": "300",
        "TARGET_COMPRESSION_RATIO": "100"
      }
    }
  }
}

快速开始

1.设置工作流（推荐的第一步）

安装MCP服务器后，设置推荐的工作流：

In Claude Code:
"Set up the spec-only workflow for me"

Claude will use setup_workflows_tool to create:
- .claude/workflows/spec-only.md
- .claude/commands/spec-only.md

现在，您可以使用 /spec-only 斜线命令：

/spec-only Add user authentication with OAuth2 support

要设置所有工作流，请执行以下操作：

"Set up all workflows"

Creates: spec-only, feature, refactor, and review workflows

2.直接使用工具

# 1. Extract facts about your codebase
query_codebase_tool(
    questions=["How is authentication implemented?"],
    scope="src/"
)
# Returns: Compressed facts with file:line references

# 2. Create specification using those facts (Claude does this)
# [Your reasoning creates A-grade spec here]

# 3. Validate specification
validate_against_codebase_tool(
    spec_content="...",
    validation_checks=["missing_files", "undefined_dependencies"]
)
# Returns: Completeness score, issues, suggestions

文档

全部文件 -你在读！
工作流程指南 -完整的工作流程文档
实施计划 -建筑细节
配置指南 -所有配置选项

工具概述

🔍 第1层：事实提取

工具	目的	关键功能
`query_codebase_tool()`	多问题分析	174:1压缩比
`find_code_by_intent_tool()`	语义搜索	返回摘要，而不是完整代码
`trace_feature_tool()`	遵循执行流程	逐步处理数据流
`list_error_patterns_tool()`	提取图案	边缘过滤

✅ 第2层：验证

工具	目的
`validate_against_codebase_tool()`	验证规格的完整性
`check_consistency_tool()`	验证图案对齐

🚀 第3层：工作流自动化

工具	目的	快速示例
`setup_workflows_tool()`	设置推荐的工作流程	`workflows=["all"]`
`generate_feature_workflow_tool()`	生成可执行工作流	逐步披露
`generate_slash_command_tool()`	创建自定义斜线命令	自动化常见任务

🔍 第4层：工具发现

工具	目的	快速示例
`discover_tools()`	按关键字、类别或用例查找工具	`query="validation"` 或 `category="fact_extraction"`
`get_tool_schema()`	获取特定工具的详细架构	`tool_name="query_codebase_tool"`

示例：完整功能实现

User: "Add Redis caching to product API"

# Step 1: Extract facts
→ query_codebase_tool(questions=[...])
← 52K tokens → 387 tokens (134:1 compression)

# Step 2: Claude creates A-grade spec using facts
→ [Your superior reasoning]
← High-quality specification

# Step 3: Validate spec
→ validate_against_codebase_tool(spec=...)
← Completeness: 92%, 1 minor issue

# Step 4: Implement
→ [Your precise code editing]

Result: ✅ A-grade spec, 61% token savings, 3.5 minutes

运作原理

特性	描述
规范创建	Claude生成A级规格
令牌使用情况	3100个克劳德代币（与传统方法相比减少61%）
双子座角色	仅提供事实
克劳德角色	用事实从头开始创造
质量	A级
工作流	自动生成

配置

关键环境变量（参见 .env.example 所有人）：

# Context & Compression
CONTEXT_CACHE_TTL_MINUTES=30     # Cache duration
MAX_TOKENS_PER_ANSWER=300        # Compression target
TARGET_COMPRESSION_RATIO=100     # Aim for 100:1
GEMINI_MODEL=auto                # or specific model

# Retry Mechanism (Exponential Backoff)
GEMINI_RETRY_MAX_ATTEMPTS=3      # Total attempts (1 initial + 2 retries)
GEMINI_RETRY_INITIAL_DELAY=1.0   # Starting delay in seconds
GEMINI_RETRY_MAX_DELAY=60.0      # Maximum delay in seconds
GEMINI_RETRY_BASE=2.0            # Exponential backoff multiplier (delay = initial * base^attempt)
GEMINI_RETRY_ENABLED=true        # Enable/disable retry mechanism

# Command/Workflow Prefixes (Namespace Management)
GEMINI_COMMAND_PREFIX=gemini-    # Prefix for generated commands
GEMINI_WORKFLOW_PREFIX=gemini-   # Prefix for generated workflows
                                 # Set to empty string to disable

用法示例

# 1. Get facts
facts = query_codebase_tool(questions=[...])

# 2. Create spec (Claude does this with superior reasoning)
spec = create_your_a_grade_spec(facts)

# 3. Validate
validate_against_codebase_tool(spec=spec)

故障排除

“找不到Gemini CLI”

npm install -g @google/gemini-cli

“双子座的空洞回应”

gemini --version  # Check installation
gemini            # Re-authenticate if needed

发展

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with debug logging
DEBUG_MODE=true python -m hitoshura25_gemini_workflow_bridge

项目结构

hitoshura25_gemini_workflow_bridge/
├── tools/           # 8 tools (Tier 1, 2, 3)
├── prompts/         # Strict fact extraction prompts
├── workflows/       # Workflow templates
├── utils/           # Token counting, prompt loading
├── server.py        # MCP server
└── generator.py     # Legacy implementations

成功指标

✅ 成本降低61% 克劳德代币
✅ 174:1压缩比 (50K → 300 代币）
✅ A级质量 规格
✅ 渐进式披露 使用工作流

贡献

欢迎投稿！请阅读：

实施计划
架构概述
提交带有测试的PR

许可证

Apache 2.0许可证-请参阅许可证

鸣谢

建筑灵感来自双子座的分析
基于 Anthropic的MCP最佳实践
内置于 FastMCP

状态： ✅ 生产就绪 最后更新时间： 2025年11月15日

🌟 如果你觉得这很有用，请在GitHub上给我们加星！