Gemini Grounding Remote

Obtém dados do usuário e informações de eventos da plataforma Connpass utilizando as APIs Connpass e Gemini.

GitHubExperimente este MCPPatrocinado

Documentação

https://github.com/rinerebox1/deno-gemini-grounding-mcp-server

Como usar

Use Docker para limpar, compilar e iniciar. O servidor MCP inicia e permanece em execução. No entanto, só com isso, não fica claro qual é a finalidade.

./start.sh

Após encerrar, execute: docker compose down

Maneira simples de iniciar o servidor MCP (sem usar Docker): deno task start

Testes: deno task test:tokyo deno task test:google_search deno task test:google_search_simple

Como adicionar um servidor MCP

  • Arquivos a implementar
    • Adicionar server.tool em index.ts
    • Definir a Tool na pasta tools (get~~.ts)
      • Formatar a saída em tools/helpers/formatHelpers.ts
    • Adicionar em tools/index.ts
    • Se for necessário adicionar bibliotecas
      • Adicionar em deno.json
      • Como atualizar o deno.lock:
        • rm -rf ~/.cache/deno && deno cache --reload index.ts
        • Verificar se a atualização foi feita com:
        • ls -la deno.lock && head -10 deno.lock
  • Código de teste
    • Implementar o código de teste na pasta tests
    • Em seguida, adicionar o arquivo de teste em tasks no deno.json
  • Como executar os testes
    • deno task test:tokyo
  • Pontos de atenção
  • Os arquivos chamados com from devem usar .ts, não .js. Cuidado, pois o LLM frequentemente altera para .js

Se os testes passarem, o servidor MCP foi implementado. Então, adicione a configuração em «C:\Users\kbpsh\OneDrive\development\MCP\deno-gemini-grounding-mcp-client» no arquivo «.gemini/settings.json». Use o servidor MCP a partir do Gemini CLI. Não inicie o «deno-gemini-grounding-mcp-client» no WSL. Como a compatibilidade entre WSL e o cliente MCP parece ruim, mantenha o cliente MCP no lado do Windows.

  • v1: Com funcionalidade Connpass + funcionalidade GenAI básica (stdio)
  • v2: Funcionalidade Connpass removida + funcionalidade GenAI especializada em turismo de Tóquio (stdio)
  • v3: Melhoria do v2 com suporte a Cloudflare Workers (funcionou bem no servidor Hono, mas não foi feito deploy no Cloudflare) (Streamable HTTP)
  • v4: Versão melhorada do v2. Adicionado o servidor MCP de grounding do Gemini. Sem suporte a Cloudflare Workers (stdio)

Preços do grounding por pesquisa do Google

https://cloud.google.com/vertex-ai/generative-ai/pricing?hl=ja

Com o Gemini Flash 2.5, é possível pesquisar gratuitamente até 1.500 consultas por dia. O Lite também é igual. Em média, cada pesquisa consome cerca de 3 consultas.

Leitura de arquivos, acesso a variáveis de ambiente, conexões de rede etc. são controlados pelo modelo de segurança do Deno por meio de flags como --allow-read, --allow-env, --allow-net, mas isso também é válido apenas 【para execução local】【não funciona remotamente】.

Registrar a MCP Tool no Cursor e no lado WSL é bastante difícil. Por enquanto, como o Gemini CLI conseguiu reconhecer o servidor MCP no lado da unidade C, consideramos OK. No entanto, mesmo no lado da unidade C, não é possível chamar a MCP Tool no Cursor, então paramos de usar MCP no Cursor.

  • O problema está na conexão entre o Cursor e o servidor MCP

    • A luz verde acende, mas o número de Tools é zero

  • É possível verificar com o seguinte comando: echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | deno run --env-file=.env --allow-net=generativelanguage.googleapis.com --allow-env --allow-read index.ts

Configuração

  1. (Pule se você já tiver obtido a chave da API Connpass) Solicite a emissão da chave da API Connpass. Para detalhes, consulte Sobre o uso da API do connpass.
  2. Clone este repositório.
  3. Configure as variáveis de ambiente necessárias. Copie .env.example para .env e defina a chave da API Connpass.
cp .env.example .env
# .envファイルを編集してCONNPASS_API_KEYを設定
  1. Inicie o servidor.

Inicialização com Deno (recomendado)

"deno-gemini-grounding-mcp-server": {
  "command": "wsl.exe",
  "args": [
    "/home/smorce/.deno/bin/deno",
    "--allow-net=generativelanguage.googleapis.com",
    "--env-file=/home/smorce/MCP/deno-gemini-grounding-mcp-server/.env",
    "--allow-read",
    "--allow-env",
    "/home/smorce/MCP/deno-gemini-grounding-mcp-server/index.ts"
  ]
}

Inicialização com Node.js

  1. Instale as dependências necessárias para iniciar o servidor MCP.
npm ci
  1. Compile o TypeScript.
npm run build
  1. Especifique o arquivo compilado no arquivo de configuração do cliente MCP.
"deno-gemini-grounding-mcp-server": {
  "command": "wsl.exe",
  "args": [
    "/home/user/.local/share/mise/installs/node/22.14.0/bin/node",
    "--env-file=/home/smorce/MCP/deno-gemini-grounding-mcp-server/.env",
    "/home/smorce/MCP/deno-gemini-grounding-mcp-server/dist/index.js"
  ]
}

Inicialização com Docker

Usando docker-compose (recomendado)

  1. Crie o arquivo de variáveis de ambiente.
# .envファイルを作成し、以下の内容を設定
echo "GEMINI_API_KEY=your_gemini_api_key_here" >> .env
  1. Inicie o serviço de acordo com a finalidade.

Diferença entre docker compose run e docker compose up

🔍 Diferença importante

docker compose up:

  • Inicia todo o serviço e continua em execução em primeiro plano
  • Os logs continuam sendo exibidos e o serviço roda até ser interrompido com Ctrl+C
  • Adequado para iniciar servidores em desenvolvimento e testes

docker compose run:

  • Usado para executar comandos únicos
  • Inicia o contêiner, executa o comando e encerra automaticamente após a conclusão
  • Adequado para chamadas a partir do cliente MCP

🔧 Para desenvolvimento/testes (execução contínua):

# 起動スクリプトを実行（クリーンアップ→ビルド→起動を自動実行）
./start.sh

Ou execute o comando docker compose manualmente.

docker compose up --build

⚡ Para MCP (execução única): Executado automaticamente por meio do cliente MCP. Para testes manuais:

docker compose run --rm deno-gemini-grounding-mcp-server

No arquivo de configuração do cliente MCP, especifique o comando docker compose run. Como o servidor MCP requer comunicação interativa via stdin/stdout, a configuração fica assim (é necessário compilar antes):

{
  "mcpServers": {
    "deno-gemini-grounding-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-e",
        "GEMINI_API_KEY=XXXXXXXXXXXXXXXX",
        "deno-gemini-grounding-mcp-server"
      ]
    }
  }
}

Uso direto do Docker

Você também pode iniciar o servidor usando o Dockerfile.

  1. Compile a imagem Docker.
docker build -t deno-gemini-grounding-mcp-server .
  1. Inicie o contêiner. A chave da API é passada como variável de ambiente.
docker run -e CONNPASS_API_KEY=XXXXXXXXXXXXXXXX -e GEMINI_API_KEY=YYYYYYYYYYYYYYYY deno-gemini-grounding-mcp-server

No arquivo de configuração do cliente MCP, especifique o comando docker.

"deno-gemini-grounding-mcp-server": {
  "command": "docker",
  "args": [
    "run",
    "-e",
    "GEMINI_API_KEY=YYYYYYYYYYYYYYYY",
    "deno-gemini-grounding-mcp-server"
  ]
}

Inicialização com npx (não recomendado)

É possível clonar este repositório e iniciar o servidor MCP com Deno ou Node.js.

"deno-gemini-grounding-mcp-server": {
  "command": "wsl.exe",
  "args": [
    "/home/smorce/.deno/bin/deno",
    "--allow-net=generativelanguage.googleapis.com",
    "--env-file=/home/smorce/MCP/deno-gemini-grounding-mcp-server/.env",
    "--allow-read",
    "--allow-env",
    "/home/smorce/MCP/deno-gemini-grounding-mcp-server/index.ts"
  ]
}

No entanto, iniciar o servidor MCP com npx não é recomendado devido a preocupações de segurança, como ataques à cadeia de suprimentos.

Funcionalidades

Oferecemos as seguintes Tools do servidor MCP:

Tools

  • get_connpass_user_list - Obtém informações básicas do usuário do Connpass

    • Parâmetros: nickname (array de nomes de usuário/apelidos do Connpass)
    • Informações obtidas: Número de eventos participados, número de eventos organizados, número de eventos apresentados, número de eventos marcados como favoritos

  • get_connpass_user_group_list - Obtém a lista de grupos aos quais o usuário do Connpass pertence

    • Parâmetros: nickname (nome de usuário/apelido do Connpass)
    • Informações obtidas: nome do grupo, URL, descrição, número de participantes etc.

  • get_connpass_user_events - Obtém informações dos eventos em que o usuário do Connpass participou

    • Parâmetros: nickname (nome de usuário/apelido do Connpass)
    • Informações obtidas: nome do evento, data/hora, local, URL, descrição

  • get_connpass_user_presenter_events - Obtém informações dos eventos em que o usuário do Connpass participou como apresentador

    • Parâmetros: nickname (nome de usuário/apelido do Connpass)
    • Informações obtidas: nome do evento, data/hora, local, URL, descrição

Exemplos de prompts

É possível passar prompts como os seguintes para o LLM:

  • «Me informe as informações de usuário do Connpass de yamanoku e okuto_oyama»
  • «Me informe as informações dos eventos do Connpass em que yamanoku participa»
  • «Exiba a lista de eventos do Connpass em que yamanoku apresentou»
  • «Exiba a lista de grupos do Connpass aos quais yamanoku pertence»

Testes

Testes com Deno

Execute testes que usam a API Gemini, como o prompt de atrativos de Tóquio:

deno task test:tokyo

Se a saída for como a abaixo, o teste foi bem-sucedido. O timeout de segurança de 30 segundos ativado é um comportamento normal.

🔍 === レスポンス検証 ===
✅ キーワード検出: 5/5
  - "東京" ✓
  - "魅力" ✓
  - "多様性" ✓
  - "文化" ✓
  - "食" ✓

🎉 テスト成功: 東京の魅力について適切にレスポンスしました！

📊 レスポンス統計:
  - 文字数: 1541
  - 行数: 15
✅ MCPサーバープロセス終了 (コード: 143)
⏰ タイムアウト: プロセスを終了します

Para detalhes sobre os testes, consulte tests/README.md.

Deno e Node.js são ambos ambientes de execução.

Agradecimentos

Este OSS teve o logotipo criado pela GPT-4o Image Generation, foi implementado pelo Claude 3.7 Sonnet e recebeu sugestões de exemplos de documentação. Agradecemos imensamente.

Licença

MIT License