Deno Gemini Grounding MCP Server

Un servidor del Protocolo de Contexto de Modelo que proporciona acceso a la API v2 de usuarios de connpass, utilizando Gemini para la fundamentación.

GitHubPrueba este MCPPatrocinado

Documentación

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

Uso

Usa Docker para limpiar, compilar e iniciar. El servidor MCP se inicia y se detiene ahí. Sin embargo, con solo esto no queda claro para qué sirve.

./start.sh

Después de finalizar, ejecuta docker compose down .

Forma sencilla de iniciar el servidor MCP (sin usar Docker): deno task start

Pruebas: deno task test:tokyo deno task test:google_search deno task test:google_search_simple

Cómo agregar un servidor MCP

  • Archivos a implementar
    • Agregar server.tool en index.ts
    • Definir Tool en la carpeta tools (get~~.ts)
      • Formateo del formato de salida en tools/helpers/formatHelpers.ts
    • Agregar a tools/index.ts
    • Si es necesario agregar una biblioteca
      • Agregar a deno.json
      • Método para actualizar deno.lock:
        • rm -rf ~/.cache/deno && deno cache --reload index.ts
        • Verificar si se actualizó con lo siguiente:
        • ls -la deno.lock && head -10 deno.lock
  • Código de prueba
    • Implementar el código de prueba en la carpeta tests
    • Luego agregar el archivo de prueba a tasks en deno.json
  • Método de ejecución de pruebas
    • deno task test:tokyo
  • Puntos de atención
  • Los archivos llamados con from deben ser .ts, no .js. Ten cuidado porque los LLM suelen cambiarlos a .js.

Si las pruebas pasan, significa que el servidor MCP está implementado, así que en «C:\Users\kbpsh\OneDrive\development\MCP\deno-gemini-grounding-mcp-client» agrega la entrada a «.gemini/settings.json». Usa el servidor MCP desde Gemini CLI. No inicies «deno-gemini-grounding-mcp-client» en WSL. Como la compatibilidad entre WSL y el cliente MCP parece mala, coloca el cliente MCP en el lado de Windows.

  • v1: Con funciones de Connpass + funciones básicas de GenAI (stdio)
  • v2: Funciones de Connpass eliminadas + funciones de GenAI especializadas en turismo de Tokio (stdio)
  • v3: Mejora de v2 con soporte para Cloudflare Workers (funcionó correctamente con el servidor Hono, pero no se ha desplegado en Cloudflare) (Streamable HTTP)
  • v4: Versión mejorada de v2. Se agregó el servidor MCP de grounding de Gemini. No tiene soporte para Cloudflare Workers (stdio)

Precios del grounding mediante búsqueda de Google

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

Con Gemini Flash 2.5 puedes realizar hasta 1500 búsquedas gratuitas al día. Lite también es igual. Una búsqueda consume aproximadamente 3 consultas.

La lectura de archivos, el acceso a variables de entorno, las conexiones de red, etc., se controlan mediante banderas como --allow-read, --allow-env, --allow-net en el modelo de seguridad de Deno, pero estas solo son [válidas únicamente en ejecución local] y [no se pueden usar de forma remota].

Registrar la herramienta MCP en Cursor y en el lado de WSL es bastante difícil. Por ahora, como el servidor MCP pudo ser reconocido desde Gemini CLI en el lado de la unidad C, lo damos por bueno. Sin embargo, como la llamada a la herramienta MCP en Cursor tampoco es posible en el lado de la unidad C, dejamos de usar MCP en Cursor.

  • El problema está en la conexión entre Cursor y el servidor MCP

    • La luz verde se enciende pero el número de herramientas es cero

  • Se puede verificar con lo siguiente. 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

Configuración

  1. (Omite si ya tienes la clave de API de Connpass) Solicita la emisión de la clave de API de Connpass. Consulta Acerca del uso de la API de connpass para más detalles.
  2. Clona este repositorio.
  3. Configura las variables de entorno necesarias. Copia .env.example a .env y configura la clave de API de Connpass.
cp .env.example .env
# .envファイルを編集してCONNPASS_API_KEYを設定
  1. Inicia el servidor.

Inicio con 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"
  ]
}

Inicio con Node.js

  1. Instala las dependencias necesarias para iniciar el servidor MCP.
npm ci
  1. Compila TypeScript.
npm run build
  1. Especifica el archivo compilado en el archivo de configuración del 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"
  ]
}

Inicio con Docker

Uso de docker-compose (recomendado)

  1. Crea el archivo de variables de entorno.
# .envファイルを作成し、以下の内容を設定
echo "GEMINI_API_KEY=your_gemini_api_key_here" >> .env
  1. Inicia el servicio según el propósito.

Diferencia entre docker compose run y docker compose up

🔍 Diferencias importantes

docker compose up：

  • Inicia todo el servicio y continúa ejecutándose en primer plano
  • Los registros se muestran continuamente y funciona hasta que se detiene con Ctrl+C
  • Adecuado para iniciar el servidor durante desarrollo y pruebas

docker compose run：

  • Se usa para ejecutar un comando único
  • Inicia el contenedor, ejecuta el comando y finaliza automáticamente al completarse
  • Adecuado para llamadas desde el cliente MCP

🔧 Para desarrollo y pruebas (ejecución continua):

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

O ejecuta manualmente el comando docker compose.

docker compose up --build

⚡ Para MCP (ejecución única): Se ejecuta automáticamente a través del cliente MCP. Para pruebas manuales:

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

En el archivo de configuración del cliente MCP, especifica el comando docker compose run. Como el servidor MCP requiere comunicación interactiva por stdin/stdout, la configuración queda de la siguiente manera (se requiere compilar primero):

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

Uso directo de Docker

También puedes iniciar el servidor usando el Dockerfile.

  1. Compila la imagen de Docker.
docker build -t deno-gemini-grounding-mcp-server .
  1. Inicia el contenedor. La clave de API se pasa como variable de entorno.
docker run -e CONNPASS_API_KEY=XXXXXXXXXXXXXXXX -e GEMINI_API_KEY=YYYYYYYYYYYYYYYY deno-gemini-grounding-mcp-server

En el archivo de configuración del cliente MCP, especifica el comando docker.

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

Inicio con npx (no recomendado)

Puedes iniciar el servidor MCP con Deno o Node.js clonando este repositorio.

"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"
  ]
}

Sin embargo, iniciar el servidor MCP con npx no se recomienda debido a preocupaciones de seguridad como ataques a la cadena de suministro.

Funciones

Se proporcionan las siguientes herramientas del servidor MCP:

Tools

  • get_connpass_user_list - Obtiene la información básica de usuarios de Connpass

    • Parámetros: nickname (arreglo de nombres de usuario/apodos de Connpass)
    • Información obtenida: Número de eventos a los que asistió, número de eventos administrados, número de eventos en los que presentó, número de eventos marcados

  • get_connpass_user_group_list - Obtiene la lista de grupos a los que pertenece un usuario de Connpass

    • Parámetros: nickname (nombre de usuario/apodo de Connpass)
    • Información obtenida: nombre del grupo, URL, descripción, número de participantes, etc.

  • get_connpass_user_events - Obtiene información de los eventos a los que asistió un usuario de Connpass

    • Parámetros: nickname (nombre de usuario/apodo de Connpass)
    • Información obtenida: nombre del evento, fecha y hora, lugar, URL, descripción

  • get_connpass_user_presenter_events - Obtiene información de los eventos en los que un usuario de Connpass participó como presentador

    • Parámetros: nickname (nombre de usuario/apodo de Connpass)
    • Información obtenida: nombre del evento, fecha y hora, lugar, URL, descripción

Ejemplos de prompts

Se pueden pasar los siguientes tipos de prompts al LLM:

  • «Dame la información de usuario de Connpass de yamanoku y okuto_oyama»
  • «Dame la información de los eventos de Connpass a los que asiste yamanoku»
  • «Muestra la lista de eventos de Connpass en los que presentó yamanoku»
  • «Muestra la lista de grupos de Connpass a los que pertenece yamanoku»

Pruebas

Pruebas con Deno

Ejecuta pruebas que usan la API de Gemini, como el prompt de atractivos de Tokio:

deno task test:tokyo

Si la salida es como la siguiente, es un éxito. Que se active el tiempo de espera de seguridad de 30 segundos es un comportamiento normal.

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

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

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

Consulta tests/README.md para más detalles sobre las pruebas.

Deno y Node.js son ambos entornos de ejecución.

Agradecimientos

Este OSS fue creado con el logotipo generado por GPT-4o Image Generation, implementado por Claude 3.7 Sonnet, y se nos propusieron ejemplos de documentación. Les agradecemos.

Licencia

MIT License