Gemini MCP Local

Codementor

语言：英语|土耳其语（README.tr.md）

CodeMentor是一个轻量级的模型上下文协议（MCP）服务器，您可以直接在计算机上运行，也可以使用启动ad-hoc npx它公开了与原始Smithery兼容服务器中使用的相同的丰富分析工作流，没有Supabase、DuckDB或代理依赖关系。通过环境变量携带您自己的API密钥，选择传输(stdio 默认情况下， http 当您需要时），您就可以从Claude Desktop或任何符合MCP的客户端进行连接。

______________________________________________________________________

快速开始

立即跑步 npx

使用Gemini CLI提供程序（默认-OAuth）：

# Make sure gemini CLI is installed and authenticated
npm install -g @google/gemini-cli
gemini  # Then select "Login with Google"

# Run the server
npx codementor

使用API密钥（可选）：

# ⚠️ SECURITY WARNING: Never hardcode API keys in config files!
# Set the API key as an environment variable instead:
export GOOGLE_API_KEY="your-google-or-gemini-key"
LLM_DEFAULT_PROVIDER=gemini npx codementor

默认情况下，CLI在STDIO传输上启动，因此它可以立即为Claude Desktop和其他本地MCP客户端做好准备。

本地安装

git clone 
cd codementor
npm install
npm run build
npm start

使用 npm run start:local 在开发过程中，如果你想实时执行TypeScript ts-node.

______________________________________________________________________

配置

所有行为都是由环境变量驱动的。只应设置您需要的提供程序密钥。

默认提供程序

默认情况下，服务器使用 Gemini CLI提供商 (gemini-cli)通过OAuth身份验证 gemini CLI工具。这允许您使用现有的Gemini Code Assist订阅，而无需管理API密钥。

要使用Gemini CLI提供程序，请执行以下操作：

1. 全局安装Gemini CLI： npm install -g @google/gemini-cli
2. 身份验证： gemini （然后选择OAuth的“使用谷歌登录”）
3. 服务器将自动使用您的OAuth凭据

若要切换回基于API密钥的身份验证，请设置 LLM_DEFAULT_PROVIDER=gemini 或 LLM_DEFAULT_PROVIDER=google.

核心服务器设置

提供程序API密钥（全部可选）

⚠️ 安全警告： 切勿在配置文件中硬编码API密钥！始终使用环境变量或系统级机密管理。致力于版本控制的API密钥可能会被暴露，并导致未经授权的访问和财务损失。

Gemini CLI提供程序（默认-推荐）：

• 通过以下方式使用OAuth身份验证 gemini CLI工具
• 不需要API密钥
• 需要 @google/gemini-cli 全球安装
• 支持 gemini-2.5-pro 和 gemini-2.5-flash 模型

注： 对于高流量或生产环境，建议将API密钥与本机SDK一起使用，以避免 stdoutLock 瓶颈。

标准API关键提供商： 设置您计划呼叫的提供商；共享解析器首先查看请求参数，然后查看这些环境变量。

将API键设置为环境变量 （从不在配置文件中）：

• GOOGLE_API_KEY / GEMINI_API_KEY
• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• PERPLEXITY_API_KEY
• MISTRAL_API_KEY
• GROQ_API_KEY
• OPENROUTER_API_KEY
• XAI_API_KEY
• AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT
• OLLAMA_API_KEY, OLLAMA_HOST

Gemini模具仍然很受欢迎 geminiApiKey 请求参数和 GEMINI_API_KEY 使用时用于向后兼容性的环境变量 gemini 或 google 供应商。

______________________________________________________________________

运输

• STDIO（默认）： 非常适合Claude Desktop或任何本地MCP编排器。从开始 npx codementor 或 npm start 并将您的客户端指向二进制文件。
• HTTP： 集 MCP_TRANSPORT_TYPE=http （以及可选 MCP_HTTP_PORT / MCP_HTTP_HOST).服务器在以下位置公开MCP可流式传输HTTP端点 `http://:

/mcp`.

两种运输方式的日志均在 logs/activity.log 和 logs/error.log。删除要重置的目录。

HTTP身份验证（可选）

对于HTTP传输，您可以启用简单的API密钥身份验证：

# Set an API key to require authentication
export MCP_API_KEY="your-secure-api-key-here"
export MCP_TRANSPORT_TYPE=http
npm start

当 MCP_API_KEY 设置，则所有HTTP请求都必须通过以下方式包含API密钥：

• 授权标头： Authorization: Bearer
• 自定义标题： x-api-key:

如果没有 MCP_API_KEY 已配置，身份验证已禁用，允许所有请求（适用于本地开发）。

⚠️ 安全说明： 这是一种适用于开发和可信环境的轻量级身份验证机制。对于生产部署，请使用具有正确JWT/OIDC身份验证、mTLS或API网关的反向代理。

HTTP会话存储（可选Redis）

默认情况下，HTTP会话在内存中跟踪，这适用于单进程部署。对于需要负载均衡器后面的会话粘性的多实例或集群部署，启用Redis支持的会话协调：

# Enable Redis-backed session ownership tracking
export MCP_SESSION_STORE=redis
export REDIS_URL="redis://localhost:6379"
# Optional key prefix (defaults to mcp:sessions:)
export REDIS_PREFIX="mcp:sessions:"

笔记：

• 仅保留会话所有权元数据（实例ID），不保留传输对象。
• 这使得路由层能够基于所有者实例实现粘性。
• 如果Redis不可用，则在以下情况下回退到内存中 MCP_SESSION_STORE=memory.
• ioredis 声明为可选依赖项；仅在启用Redis会话协调时安装(MCP_SESSION_STORE=redis).默认内存模式不需要它。

⚠️ 多实例部署警告：\ 当使用HTTP传输运行多个服务器实例（集群/Kubernetes）时 必须 启用 粘性会话（会话亲和性） 在您的负载均衡器上。如果没有粘性会话，当请求被路由到不同的实例时，SSE（服务器发送事件）连接可能会中断。使用Redis支持的会话协调(MCP_SESSION_STORE=redis)跨实例跟踪会话所有权。

______________________________________________________________________

工具亮点

服务器公开了一个全面的分析工作流程，包括：

• 综合项目分析 通过专家角色选择和人工智能提供的见解。
• 目标代码搜索 用于在大型存储库中定位文件、函数或模式的实用程序。
• 知识获取工具 用于使用指南、常见问题综合和报告生成。
• 代币会计 （与Gemini兼容）计划具有git diff支持的安全响应大小。
• 高效的代码库分析 通过.mcpinore和子目录分析进行智能上下文过滤。

每个工具都使用Zod模式验证输入，并自动记录包含请求上下文ID的结构化日志，以便于跟踪。

______________________________________________________________________

工具亮点

服务器通过以下方式公开了一个全面的分析工作流 CodeMentor元素套件:

• 🔥 点燃：初始化项目，设置优化规则，并准备环境。
• 👁️ 洞察：核心分析引擎。使用Gemini审查代码、解释架构并发现错误。
• 🔨 锻造：根据您的项目创建专门的专家角色（例如“数据库优化器”、“安全审计员”）。
• ⚖️ 称重：计算令牌使用情况，以帮助您规划分析策略并避免限制。

______________________________________________________________________

使用Git差异分析进行代码审查

这 insight 该工具支持与git diff集成的代码审查模式：

审查未承诺的变更

{
  "tool_name": "insight",
  "params": {
    "projectPath": "./",
    "question": "Review my changes for security issues and code quality",
    "analysisMode": "review",
    "includeChanges": { "revision": "." }
  }
}

审查具体承诺

{
  "projectPath": "./",
  "question": "Analyze this commit for potential bugs",
  "analysisMode": "review",
  "includeChanges": { "revision": "a1b2c3d" }
}

回顾最近N次提交

{
  "projectPath": "./",
  "question": "Review recent changes",
  "analysisMode": "review",
  "includeChanges": { "count": 5 }
}

查看功能

• 专业AI提示：专注于安全性、性能和最佳实践的专家代码审查员角色
• 结构化JSON差异：AI以机器可读格式接收更改
• 完整上下文：与整个代码库一起分析的更改
• 边缘案例处理：适用于初始提交、二进制文件和空差异
• 大文件保护：文件超过 MAX_GIT_BLOB_SIZE_BYTES （默认4MB）会自动跳过以防止内存问题。跳过的文件将在分析输出中报告。

处理大型项目

对于超出令牌限制的项目，请使用以下策略：

1. 使用 .mcpignore：添加模式以排除不必要的文件（类似于 .gitignore)

   node_modules/
   dist/
   *.test.ts
   docs/

1. 使用 temporaryIgnore：排除特定分析的文件

   {
     "projectPath": "./",
     "question": "Analyze core logic",
     "temporaryIgnore": ["tests/**", "docs/**"]
   }

1. 分析子目录：专注于项目的特定部分

   {
     "projectPath": "./src/core",
     "question": "Review core functionality"
   }

分析模式

这 analysisMode 参数支持以下模式：

• general -综合项目分析
• implementation -功能实现指南
• refactoring -代码质量改进
• explanation -教育解释
• debugging -Bug识别和修复
• audit -完成代码审核
• security -安全漏洞评估
• performance -性能优化
• testing -测试策略和创建
• documentation -文档生成
• review -使用git diff分析进行代码更改审查⭐ 新

______________________________________________________________________

自定义分析模式

CodeMentor现在支持 自定义分析模式 这允许您创建、保存和重用用于代码分析的专门专家提示。

创建自定义模式

使用 forge 随着 saveAs 保存自定义模式的参数：

{
  "tool_name": "forge",
  "params": {
    "expertiseHint": "Create a React performance optimization expert",
    "withAi": true,
    "saveAs": "react-perf-expert"
  }
}

这创造了 .mcp/analysis_modes/react-perf-expert.md 在你的项目中。

列出可用模式

列出所有可用的分析模式（标准+自定义）：

{
  "tool_name": "forge",
  "params": {
    "action": "list"
  }
}

删除自定义模式

删除自定义分析模式：

{
  "tool_name": "forge",
  "params": {
    "action": "delete",
    "modeName": "react-perf-expert"
  }
}

使用自定义模式

在中引用您保存的模式 insight 随着 custom: 前缀：

{
  "tool_name": "insight",
  "params": {
    "projectPath": ".",
    "analysisMode": "custom:react-perf-expert",
    "question": "Analyze the ProductDetail component for performance issues"
  }
}

益处

• ✅ 可重复使用的：创建一次，使用多次
• ✅ 可共享的：致力于团队使用的版本控制
• ✅ 灵活的：手动、人工智能辅助或项目特定模式
• ✅ 有组织的：存储在 .mcp/analysis_modes/ 目录
• ✅ 可管理的：根据需要列出和删除模式（v5.1.0+）

📖 有关完整文档，请参阅 定制_分析_设计.md

📖 有关锻造工具的详细信息，请参阅 docs/tools/forge.md

______________________________________________________________________

安全/身份验证

API密钥验证（HTTP传输）

使用HTTP传输时，服务器支持通过 MCP_API_KEY 环境变量：

# Enable API key authentication
export MCP_API_KEY="your-secure-api-key-here"
export MCP_TRANSPORT_TYPE=http
npm start

身份验证方法：

• 授权标头： Authorization: Bearer
• 自定义标题： x-api-key:

如果没有 MCP_API_KEY 已配置，身份验证已禁用，允许所有请求（适用于本地开发）。

生产安全建议

⚠️ 重要安全注意事项：

• 服务器本身不提供JWT/OAuth层
• API密钥认证是一种适用于开发和可信环境的轻量级机制
• 对于生产部署，在服务器前放置一个反向代理（例如Nginx）以提高安全性

推荐的生产设置：

• 使用具有适当身份验证/授权的反向代理
• 在代理级别实现TLS终止
• 考虑mTLS、JWT/OIDC验证或API网关解决方案
• 应用网络分段和IP分配列表
• 使用Web应用程序防火墙（WAF）提供额外保护

访问模型

• HTTP和STDIO MCP端点不实现内置的基于作用域的授权
• 此服务器适用于本地和受控环境（例如，与编辑器一起运行或在自己的基础设施后面运行）
• 工具和资源无需服务器端范围检查即可调用；任何 withRequiredScopes helper是一个no操作，仅用于向后兼容的导入，不得将其视为安全控件

安全和架构亮点

安全路径处理（BASE_DIR+validateSecurePath）

所有文件系统访问都限制在一个定义良好的项目根目录下(BASE_DIR).辅助工具（例如 validateSecurePath)阻止路径遍历，并禁止解析此基目录之外的文件。这适用于代码库分析、差异加载和任何文件支持的MCP资源。

速率限制和Redis支持

该服务器包括一个防御速率限制器，用于保护上游LLM API和您的基础设施。

• 默认存储：内存中（适用于本地/单节点使用）。
• Redis后端：启用：

- MCP_RATE_LIMIT_STORE=redis - REDIS_URL=redis://user:pass@host:6379/0

• 密钥的身份层次结构（最具体的获胜）：

1. userId 1. clientId 1. ip 1. anon:global

这允许跨异构客户端的公平使用和滥用保护。

会话存储

HTTP会话所有权元数据遵循相同的可插拔模式：

• 内存中（默认）用于简单/本地设置。
• Redis支持时 MCP_SESSION_STORE=redis 设置，实现跨多个实例的一致路由和粘性。

CI/CD安全控制

推荐的管道围绕安全发布进行加固：

• 依赖性扫描（例如。 npm audit --production --audit-level=high)在关键路径上。
• 用于安全回归的CodeQL（或等效）静态分析。
• 自动更新依赖关系（例如Dependabot），以便及时修补。
• publish.yml 基于语义版本标签的门控(v*.*.*)保持发布可审计。

日志重设

对日志中的敏感值进行了严格的编辑。

• 通过以下方式配置编校 MCP_REDACT_KEYS （逗号分隔）。
• 与这些密钥匹配的秘密在内部记录器生成的结构化日志中被掩盖。

______________________________________________________________________

安全

安全强化指南： 有关全面的生产硬化建议，请参阅 docs/security-hardening.md 在存储库中。

关键安全原则：

• 将此MCP服务器视为内部组件
• 在反向代理或API网关上终止TLS
• 在网关级别执行身份验证/授权
• 强制网络边界和IP分配
• 切勿在配置文件中硬编码API密钥

Git命令执行

查看模式执行git命令以提取差异。安全措施：

• 所有修订字符串都会根据严格的正则表达式进行验证
• 外壳元字符被阻止
• 用途 simple-git 防止命令注入的库
• 通过路径遍历保护 validateSecurePath

______________________________________________________________________

.mcpinore支持

通过排除超出范围的文件来优化MCP上下文 .gitignoreThe .mcpignore 文件工作 在...之上 .gitignore （附加）允许您从AI分析中排除测试文件、文档和其他文件，而无需修改您的 .gitignore.

运作原理

1. .gitignore 首先加载图案
2. .mcpignore 图案被添加到顶部
3. 所有MCP工具（代码搜索、令牌计数、代码库分析器等）都尊重这两个文件

创建.mcpinore

复制示例文件并根据需要进行自定义：

cp .mcpignore.example .mcpignore

常见用例

从AI上下文中排除测试文件：

# .mcpignore
**/*.test.ts
**/*.spec.ts
**/tests/**
__tests__/**

不包括文档：

# .mcpignore
docs/**
*.md
!README.md

排除生成的文件：

# .mcpignore
**/generated/**
**/*.generated.ts

看 .mcpignore.example 了解更多模式和示例。

向后兼容

• 如果 .mcpignore 不存在，工具只能正常工作 .gitignore
• 所有现有 .gitignore 功能得以保留
• 该功能完全可选

______________________________________________________________________

代码元数据提取

该服务器包括高级代码元数据提取功能，由 树型AST解析 为了提高准确性，特别是对于复杂的语法结构（嵌套类、装饰器、泛型）。

支持的语言

树保姆解析已启用：

• Java -类、接口、方法、导入
• 去 -类型、功能、导入
• 锈 -结构、枚举、特征、函数、use语句
• C -类、接口、方法、使用语句
• 红宝石 -类、模块、方法、require语句
• PHP -类、接口、特性、函数、use语句
• python -类、函数、导入语句

JavaScript/TypeScript文件使用Babel AST解析（已经实现）。

混合回退策略

该系统使用优雅的降级方法：

1. 树型AST解析 （最佳精度）-支持语言的主要方法
2. 正则表达式模式匹配 （可接受）-如果树保姆失败或不可用，则回退
3. 最小元数据 （基本）-如果所有解析方法都失败，则最终回退

这确保了即使语法包丢失或解析遇到错误，系统也能继续工作。

演出

• 语法加载：首次使用时\<500ms（此后缓存）
• 解析时间：每个文件\<100ms（平均）
• 内存开销：所有语法缓存\<50MB
• 语法包加载缓慢（仅在需要时）

故障排除

如果Tree sitter解析失败：

• 系统自动回退到正则表达式解析
• 检查是否安装了可选语法包： npm install
• 语法包是可选的依赖项-缺少包会触发正则表达式回退
• 检查日志以获取详细的错误消息

______________________________________________________________________

开发命令

______________________________________________________________________

项目布局

src/
├── config/            # Environment parsing & validation with Zod schemas
├── mcp-server/        # Reusable MCP server scaffolding (STDIO + HTTP transports)
│   ├── tools/        # MCP tool implementations
│   ├── transports/   # STDIO and HTTP transport layers
│   └── utils/        # Server-specific utilities
├── services/
│   └── llm-providers/ # LLM provider integrations (Gemini CLI, OpenRouter, etc.)
├── utils/             # Shared utilities (logging, error handling, security, parsing)
├── types-global/      # Global type definitions
└── index.ts           # Main entry point and CLI bootstrap

注： 遗留代理、Supabase、DuckDB和部署工件已被删除。如果你需要它们，请在 2.0.0 释放。

架构概述

代码库遵循分层架构，关注点明确分离：

• 入口点 (src/index.ts)：用于嵌入MCP服务器的程序化引导
• 配置 (src/config/)：使用Zod进行环境解析和验证
• MCP服务器 (src/mcp-server/)：使用STDIO和HTTP传输的可重用服务器支架
• 工具 (src/mcp-server/tools/)：MCP工具实现（分析、令牌计数等）
• 服务 (src/services/)：外部服务集成（LLM提供商）
• 公用事业 (src/utils/)：共享实用程序（日志记录、错误处理、安全性、解析）

有关包括组件映射、请求流和安全考虑在内的详细架构文档，请参阅 docs/ 存储库中的目录。

______________________________________________________________________

从游标连接

有关在 Cursor 中使用 MCP 的详细安装说明 CURSOR_SETUP.md 看看档案。

快速安装：

1. 安装Gemini CLI并进行身份验证：

npm install -g @google/gemini-cli
gemini  # "Login with Google" seçeneğini seçin

1. 创建 Cursor MCP 配置文件 cursor_mcp_config.json 添加内容。

1. 重新启动 Cursor。

从克劳德桌面连接

使用样本 claude_desktop_config.example.json 或者复制下面的块并替换所需的值：

{
  "mcpServers": {
    "codementor": {
      "command": "npx",
      "args": ["-y", "codementor"],
      "env": {
        "LLM_DEFAULT_PROVIDER": "gemini-cli"
      }
    }
  }
}

或者使用API密钥验证(⚠️ 安全警告： 永远不要在配置文件中硬编码API密钥！请改用环境变量）：

{
  "mcpServers": {
    "codementor": {
      "command": "npx",
      "args": ["-y", "codementor"],
      "env": {
        "LLM_DEFAULT_PROVIDER": "gemini"
        // DO NOT add GOOGLE_API_KEY here - set it as an environment variable instead!
      }
    }
  }
}

______________________________________________________________________

已知限制

Gemini CLI提供程序并发

使用时 gemini-cli 提供程序（默认），并发请求被序列化以防止stdout冲突。这是已知的限制 ai-sdk-provider-gemini-cli 图书馆。

影响：

• 多个同时进行的请求将按顺序处理
• 可能影响高负载下的性能
• 对于典型的单用户IDE使用来说，这不是问题

解决方法：

• 对于高级货币场景，请使用基于API密钥的提供程序(gemini, google, openai)
• 集 LLM_DEFAULT_PROVIDER=gemini 并提供 GOOGLE_API_KEY 环境变量
• API密钥提供程序支持完全并发请求处理

例子：

# Switch to API key provider for better concurrency
export GOOGLE_API_KEY="your-api-key"
export LLM_DEFAULT_PROVIDER=gemini
npx codementor

此限制记录在代码库中 src/services/llm-providers/geminiCliProvider.ts 并且不影响系统的安全性或正确性。

______________________________________________________________________

后续步骤

• 添加新工具 src/mcp-server/tools/ 遵循既定模式（参见 .kiro/steering/mcp-workflows.md)
• 通过添加新的提供程序来扩展LLM提供程序支持 src/services/llm-providers/
• 使用重建API文档 npm run docs:generate 更改后
• 使用自定义分析模式 forge 针对您的特定用例

享受更精简的设置！