[{"_1":2,"_316":-5,"_317":-5},"loaderData",{"_3":4,"_22":23,"_24":25,"_256":257},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":17,"_18":-5,"_19":20,"_21":-5},"attributes",[15],"BOT","id",6032519,"membership","referenceId","0196aafb-187b-7f6f-9a8e-393d43c2126a","userAccount","routes/_public/_layout",{},"routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_26":27,"_68":-5,"_69":28,"_29":70,"_174":175,"_255":127},"availableLocales",[28,40,47,54,61],{"_29":30,"_33":37,"_38":39},"mcpServer",{"_31":32,"_33":34,"_35":36},"description","A Model Context Protocol server that provides tools for interacting with databases, including PostgreSQL, DuckDB, and Google Cloud Storage Parquet files.","name","MCP Database Server","readme","# MCP Database Server\n\nA Model Context Protocol (MCP) server built with `mcp-framework` that provides tools and resources for interacting with databases (PostgreSQL via DuckDB) and Google Cloud Storage (GCS).\n\n## Prerequisites\n\n- Node.js 22 or higher\n- TypeScript\n- PostgreSQL (required for database features)\n- Google Cloud credentials (optional, for GCS features)\n- [Devbox](https://www.jetpack.io/devbox/) (for local development using `make` commands)\n\n## Project Structure\n\n```plaintext\n.\n├── docs\n│ ├── assets\n│ │ └── etl.png\n│ ├── etl-workflow.md\n│ └── setup-with-claude-desktop.md\n├── migrations\n│ ├── 1743322886782_initial-schema.cjs\n│ └── 1743323460433_continuous-aggregates.cjs\n├── scripts\n│ └── setup-continuous-aggregates.sql\n├── src\n│ ├── resources # MCP Resource definitions\n│ │ ├── gcs_objects.ts\n│ │ └── sql_tables.ts\n│ ├── services # Service initializers (DB connections, GCS client)\n│ │ ├── duckdb.ts\n│ │ ├── gcs.ts\n│ │ └── postgres.ts\n│ ├── tools # MCP Tool definitions\n│ │ ├── duckdb_insert.ts\n│ │ ├── duckdb_query.ts\n│ │ ├── duckdb_read_parquet.ts\n│ │ └── gcs_directory_tree.ts\n│ ├── utils # Utility functions (logging, formatting)\n│ │ ├── index.ts\n│ │ └── logger.ts\n│ ├── config.ts # Configuration loading and validation\n│ ├── index.ts # Main server entry point\n│ └── utils.ts # Deprecated utils? (Consider removing if unused)\n├── .env.example # Example environment variables\n├── .gitignore\n├── CLAUDE.md\n├── Dockerfile\n├── MIGRATION.md\n├── Makefile # Development commands\n├── README.md\n├── database.json # Migration configuration\n├── devbox.json # Devbox configuration\n├── devbox.lock\n├── docker-compose.yml # Docker setup for DBs\n├── fly.toml # Fly.io deployment config\n├── package-lock.json\n├── package.json\n└── tsconfig.json\n```\n\n## Installation\n\n1. Clone the repository:\n\n ```bash\n git clone \n cd mcp-db\n ```\n\n2. Install dependencies (using Devbox is recommended for consistency):\n\n ```bash\n devbox install\n # Or using npm directly if not using Devbox\n # npm install\n ```\n\n3. Copy `.env.example` to `.env` and fill in your environment variables.\n\n ```bash\n cp .env.example .env\n # Edit .env with your details\n ```\n\n4. Build the project:\n\n ```bash\n # Using make (requires Devbox)\n make build\n # Or using npm directly\n # npm run build\n ```\n\n## Configuration\n\n### Environment Variables\n\nConfigure the server using these environment variables (or command-line arguments):\n\n- `DATABASE_URL`: PostgreSQL connection string (required unless running with supergateway).\n- `DATABASE_URLS`: Comma-separated list of `alias=url` pairs for multiple database connections (alternative to `DATABASE_URL`).\n- `LOG_LEVEL`: Logging level (`debug`, `info`, `error`). Default: `info`.\n- `GCS_BUCKET`: Default Google Cloud Storage bucket name (optional).\n- `GCP_SERVICE_ACCOUNT`: Base64 encoded Google Cloud service account key JSON (optional, for GCS authentication).\n- `GCS_KEY_ID` / `GCS_SECRET`: Alternative GCS credentials specifically for DuckDB's `httpfs` extension (optional).\n- `TRANSPORT`: Transport type (`stdio` or `sse`). Default: `stdio`.\n- `PORT`: Port number for SSE transport. Default: `3001`.\n- `HOST`: Hostname for SSE transport. Default: `localhost`.\n- `API_KEY`: Optional API key for securing the server (if set, clients must provide it in the `Authorization: Bearer ` header).\n\nCommand-line arguments (e.g., `--port 8080`, `--gcs-bucket my-bucket`) override environment variables. See `src/config.ts` for details.\n\n## Database Migrations\n\nThe project uses `node-pg-migrate` for managing PostgreSQL schema changes. See the \"Database Migrations\" section in the original README content above for details on running and creating migrations.\n\n**Note:** The `npm run setup:db` command mentioned previously might need review or updates based on the current setup.\n\n## Running the Server\n\nUse the `Makefile` for convenient development commands (requires Devbox):\n\n```bash\n# Run in development mode (builds and starts with nodemon for auto-restarts)\n# Uses SSE transport by default on port 3001\nmake dev\n\n# Run tests (if configured)\n# make test\n\n# Build for production\n# make build\n```\n\nTo run without `make` (after `npm run build`):\n\n```bash\n# Run with stdio transport\nnode dist/index.js --transport stdio\n\n# Run with SSE transport on default port 3001\nnode dist/index.js --transport sse\n\n# Run with SSE on a different port\nnode dist/index.js --transport sse --port 8080\n```\n\n### Client Configuration\n\nTo connect your MCP client (e.g., `mcp-cli`, Claude Desktop) to the local server:\n\n**For SSE Transport (e.g., on port 3001):**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"sse\",\n \"--port\", \"3001\" // Match the port the server is running on\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n*(Note: The Docker/supergateway example from the previous README might be outdated or specific to a different deployment setup.)*\n\n**For Stdio Transport:**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"stdio\"\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n### Running with npx from GitHub\n\nYou can run the server directly using npx (requires build step in package):\n\n```bash\n# Ensure required env vars are set\nexport DATABASE_URL=\"postgresql://user:password@localhost:5432/db\"\nexport GCS_BUCKET=\"my-bucket\"\n\nnpx github:dwarvesf/mcp-db --transport sse --port 3001\n```\n\n## Available Tools\n\n- `duckdb_insert`: Executes an `INSERT` statement on the attached PostgreSQL database via DuckDB. Only `INSERT` queries are allowed.\n- `duckdb_query`: Executes a read-only SQL query directly on the attached PostgreSQL database (`postgres_db`) using DuckDB's `postgres_query` function. Automatically prefixes unqualified table names (e.g., `my_table` becomes `postgres_db.public.my_table`).\n- `duckdb_read_parquet`: Queries Parquet files using DuckDB (likely from GCS if configured).\n- `duckdb_update`: Executes an `UPDATE` statement on the attached PostgreSQL database via DuckDB.\n- `gcs_directory_tree`: Fetches the directory tree structure from a GCS bucket with pagination support.\n\n## Available Resources\n\n- `mcp://gcs/objects`: Lists objects in the configured GCS bucket.\n- `mcp://db/tables`: Lists all tables and their columns in the configured PostgreSQL database.\n\n## Development: Integrating a New Tool/Resource\n\nThis project uses `mcp-framework`. To add a new tool or resource:\n\n1. **Create the Class:**\n - Create a new `.ts` file in `src/tools/` or `src/resources/`.\n - Define a class that extends `MCPTool` or `MCPResource`.\n - Implement the required properties (`name`, `description`, `schema` for tools) and methods (`execute` for tools, `read` for resources).\n - Use Zod in the `schema` property for input validation (tools).\n - Initialize any dependencies (like DB connections or GCS clients) within the class, often in the constructor, potentially using services from `src/services/` or configuration from `src/config.ts`.\n\n *Example Tool (`src/tools/my_tool.ts`):*\n\n ```typescript\n import { MCPTool } from \"mcp-framework\";\n import { z } from \"zod\";\n import { formatSuccessResponse } from \"../utils.js\";\n import { getDuckDBConnection } from \"../services/duckdb.js\"; // Example dependency\n\n const MyToolInputSchema = z.object({\n param1: z.string().describe(\"Description for parameter 1\"),\n });\n type MyToolInput = z.infer;\n\n export class MyTool extends MCPTool {\n name = \"my_tool\";\n description = \"Description of what my tool does.\";\n schema = { // Matches Zod schema structure\n param1: { type: z.string(), description: \"Description for parameter 1\" },\n };\n\n async execute(args: MyToolInput): Promise {\n console.error(`Handling tool request: ${this.name}`);\n const duckDBConn = getDuckDBConnection(); // Get dependency\n // ... implement logic using args and duckDBConn ...\n const result = { message: `Processed ${args.param1}` };\n return formatSuccessResponse(result);\n }\n }\n export default MyTool; // Ensure default export\n ```\n\n2. **Automatic Discovery:**\n - `mcp-framework` automatically discovers and registers tool/resource classes that are default-exported from files within the `src/tools` and `src/resources` directories.\n - Ensure your new class is the `default export` in its file.\n\n3. **Test:**\n - Run the server (`make dev`).\n - Check the startup logs to ensure your new tool/resource is listed.\n - Use an MCP client (like `mcp-cli` or the MCP Inspector) to call the tool or read the resource and verify its functionality.\n\n### Best Practices\n\n- Define clear input schemas using Zod for tools.\n- Handle errors gracefully within `execute`/`read` and return formatted error responses using `formatErrorResponse` (or throw errors).\n- Use the centralized configuration (`src/config.ts`) via `getConfig()` where needed.\n- Leverage the service initializers in `src/services/` for dependencies like database connections.\n- Add logging (`console.error`) for visibility.\n","English","tag","en-US",{"_29":41,"_33":45,"_38":46},{"_31":42,"_33":43,"_35":44},"Un servidor de protocolo de contexto de modelo que proporciona herramientas para interactuar con bases de datos, incluidos archivos PostgreSQL, DuckDB y Google Cloud Storage Parquet.","Servidor de base de datos MCP","# Servidor de base de datos MCP\n\nUn servidor de Protocolo de Contexto de Modelo (MCP) creado con `mcp-framework` que proporciona herramientas y recursos para interactuar con bases de datos (PostgreSQL a través de DuckDB) y Google Cloud Storage (GCS).\n\n## Prerrequisitos\n\n* Node.js 22 o superior\n* Mecanografiado\n* PostgreSQL (necesario para las funciones de la base de datos)\n* Credenciales de Google Cloud (opcionales, para funciones de GCS)\n* [Devbox](https://www.jetpack.io/devbox/) (para desarrollo local usando comandos `make` )\n\n## Estructura del proyecto\n\n```plaintext\n.\n├── docs\n│ ├── assets\n│ │ └── etl.png\n│ ├── etl-workflow.md\n│ └── setup-with-claude-desktop.md\n├── migrations\n│ ├── 1743322886782_initial-schema.cjs\n│ └── 1743323460433_continuous-aggregates.cjs\n├── scripts\n│ └── setup-continuous-aggregates.sql\n├── src\n│ ├── resources # MCP Resource definitions\n│ │ ├── gcs_objects.ts\n│ │ └── sql_tables.ts\n│ ├── services # Service initializers (DB connections, GCS client)\n│ │ ├── duckdb.ts\n│ │ ├── gcs.ts\n│ │ └── postgres.ts\n│ ├── tools # MCP Tool definitions\n│ │ ├── duckdb_insert.ts\n│ │ ├── duckdb_query.ts\n│ │ ├── duckdb_read_parquet.ts\n│ │ └── gcs_directory_tree.ts\n│ ├── utils # Utility functions (logging, formatting)\n│ │ ├── index.ts\n│ │ └── logger.ts\n│ ├── config.ts # Configuration loading and validation\n│ ├── index.ts # Main server entry point\n│ └── utils.ts # Deprecated utils? (Consider removing if unused)\n├── .env.example # Example environment variables\n├── .gitignore\n├── CLAUDE.md\n├── Dockerfile\n├── MIGRATION.md\n├── Makefile # Development commands\n├── README.md\n├── database.json # Migration configuration\n├── devbox.json # Devbox configuration\n├── devbox.lock\n├── docker-compose.yml # Docker setup for DBs\n├── fly.toml # Fly.io deployment config\n├── package-lock.json\n├── package.json\n└── tsconfig.json\n```\n\n## Instalación\n\n1. Clonar el repositorio:\n\n ```bash\n git clone \n cd mcp-db\n ```\n\n2. Instalar dependencias (se recomienda utilizar Devbox para mantener la coherencia):\n\n ```bash\n devbox install\n # Or using npm directly if not using Devbox\n # npm install\n ```\n\n3. Copie `.env.example` a `.env` y complete sus variables de entorno.\n\n ```bash\n cp .env.example .env\n # Edit .env with your details\n ```\n\n4. Construir el proyecto:\n\n ```bash\n # Using make (requires Devbox)\n make build\n # Or using npm directly\n # npm run build\n ```\n\n## Configuración\n\n### Variables de entorno\n\nConfigure el servidor utilizando estas variables de entorno (o argumentos de línea de comandos):\n\n* `DATABASE_URL` : cadena de conexión PostgreSQL (obligatoria a menos que se ejecute con supergateway).\n* `DATABASE_URLS` : Lista separada por comas de pares `alias=url` para múltiples conexiones de base de datos (alternativa a `DATABASE_URL` ).\n* `LOG_LEVEL` : Nivel de registro ( `debug` , `info` , `error` ). Predeterminado: `info` .\n* `GCS_BUCKET` : nombre del depósito de Google Cloud Storage predeterminado (opcional).\n* `GCP_SERVICE_ACCOUNT` : clave JSON de cuenta de servicio de Google Cloud codificada en Base64 (opcional, para la autenticación de GCS).\n* `GCS_KEY_ID` / `GCS_SECRET` : Credenciales GCS alternativas específicamente para la extensión `httpfs` de DuckDB (opcional).\n* `TRANSPORT` : Tipo de transporte ( `stdio` o `sse` ). Predeterminado: `stdio` .\n* `PORT` : Número de puerto para el transporte SSE. Predeterminado: `3001` .\n* `HOST` : Nombre de host para el transporte SSE. Predeterminado: `localhost` .\n* `API_KEY` : Clave API opcional para proteger el servidor (si se configura, los clientes deben proporcionarla en el encabezado `Authorization: Bearer ` ).\n\nLos argumentos de la línea de comandos (p. ej., `--port 8080` , `--gcs-bucket my-bucket` ) anulan las variables de entorno. Consulte `src/config.ts` para obtener más información.\n\n## Migraciones de bases de datos\n\nEl proyecto utiliza `node-pg-migrate` para gestionar los cambios de esquema de PostgreSQL. Consulte la sección \"Migraciones de bases de datos\" del archivo README original (arriba) para obtener más información sobre cómo ejecutar y crear migraciones.\n\n**Nota:** El comando `npm run setup:db` mencionado anteriormente podría necesitar revisión o actualizaciones según la configuración actual.\n\n## Ejecución del servidor\n\nUtilice el `Makefile` para comandos de desarrollo convenientes (requiere Devbox):\n\n```bash\n# Run in development mode (builds and starts with nodemon for auto-restarts)\n# Uses SSE transport by default on port 3001\nmake dev\n\n# Run tests (if configured)\n# make test\n\n# Build for production\n# make build\n```\n\nPara ejecutar sin `make` (después de `npm run build` ):\n\n```bash\n# Run with stdio transport\nnode dist/index.js --transport stdio\n\n# Run with SSE transport on default port 3001\nnode dist/index.js --transport sse\n\n# Run with SSE on a different port\nnode dist/index.js --transport sse --port 8080\n```\n\n### Configuración del cliente\n\nPara conectar su cliente MCP (por ejemplo, `mcp-cli` , Claude Desktop) al servidor local:\n\n**Para el transporte SSE (por ejemplo, en el puerto 3001):**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"sse\",\n \"--port\", \"3001\" // Match the port the server is running on\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n*(Nota: el ejemplo de Docker/supergateway del README anterior podría estar desactualizado o ser específico para una configuración de implementación diferente).*\n\n**Para el transporte de Stdio:**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"stdio\"\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n### Ejecutando con npx desde GitHub\n\nPuede ejecutar el servidor directamente usando npx (requiere el paso de compilación en el paquete):\n\n```bash\n# Ensure required env vars are set\nexport DATABASE_URL=\"postgresql://user:password@localhost:5432/db\"\nexport GCS_BUCKET=\"my-bucket\"\n\nnpx github:dwarvesf/mcp-db --transport sse --port 3001\n```\n\n## Herramientas disponibles\n\n* `duckdb_insert` : Ejecuta una instrucción `INSERT` en la base de datos PostgreSQL adjunta mediante DuckDB. Solo se permiten consultas `INSERT` .\n* `duckdb_query` : Ejecuta una consulta SQL de solo lectura directamente en la base de datos PostgreSQL adjunta ( `postgres_db` ) mediante la función `postgres_query` de DuckDB. Prefija automáticamente los nombres de tabla no calificados (p. ej., `my_table` se convierte en `postgres_db.public.my_table` ).\n* `duckdb_read_parquet` : consulta archivos Parquet utilizando DuckDB (probablemente desde GCS si está configurado).\n* `duckdb_update` : ejecuta una declaración `UPDATE` en la base de datos PostgreSQL adjunta a través de DuckDB.\n* `gcs_directory_tree` : obtiene la estructura del árbol de directorios de un depósito GCS con soporte de paginación.\n\n## Recursos disponibles\n\n* `mcp://gcs/objects` : enumera los objetos en el depósito GCS configurado.\n* `mcp://db/tables` : enumera todas las tablas y sus columnas en la base de datos PostgreSQL configurada.\n\n## Desarrollo: Integración de una nueva herramienta/recurso\n\nEste proyecto utiliza `mcp-framework` . Para añadir una nueva herramienta o recurso:\n\n1. **Crear la clase:**\n\n * Cree un nuevo archivo `.ts` en `src/tools/` o `src/resources/` .\n * Defina una clase que extienda `MCPTool` o `MCPResource` .\n * Implemente las propiedades requeridas ( `name` , `description` , `schema` para herramientas) y métodos ( `execute` para herramientas, `read` para recursos).\n * Utilice Zod en la propiedad `schema` para la validación de entrada (herramientas).\n * Inicialice cualquier dependencia (como conexiones de base de datos o clientes GCS) dentro de la clase, a menudo en el constructor, potencialmente usando servicios de `src/services/` o configuración de `src/config.ts` .\n\n *Herramienta de ejemplo ( `src/tools/my_tool.ts` ):*\n\n ```typescript\n import { MCPTool } from \"mcp-framework\";\n import { z } from \"zod\";\n import { formatSuccessResponse } from \"../utils.js\";\n import { getDuckDBConnection } from \"../services/duckdb.js\"; // Example dependency\n\n const MyToolInputSchema = z.object({\n param1: z.string().describe(\"Description for parameter 1\"),\n });\n type MyToolInput = z.infer;\n\n export class MyTool extends MCPTool {\n name = \"my_tool\";\n description = \"Description of what my tool does.\";\n schema = { // Matches Zod schema structure\n param1: { type: z.string(), description: \"Description for parameter 1\" },\n };\n\n async execute(args: MyToolInput): Promise {\n console.error(`Handling tool request: ${this.name}`);\n const duckDBConn = getDuckDBConnection(); // Get dependency\n // ... implement logic using args and duckDBConn ...\n const result = { message: `Processed ${args.param1}` };\n return formatSuccessResponse(result);\n }\n }\n export default MyTool; // Ensure default export\n ```\n\n2. **Descubrimiento automático:**\n\n * `mcp-framework` descubre y registra automáticamente las clases de herramientas/recursos que se exportan de forma predeterminada desde los archivos dentro de los directorios `src/tools` y `src/resources` .\n * Asegúrese de que su nueva clase sea la `default export` en su archivo.\n\n3. **Prueba:**\n\n * Ejecute el servidor ( `make dev` ).\n * Verifique los registros de inicio para asegurarse de que su nueva herramienta/recurso esté en la lista.\n * Utilice un cliente MCP (como `mcp-cli` o MCP Inspector) para llamar a la herramienta o leer el recurso y verificar su funcionalidad.\n\n### Mejores prácticas\n\n* Defina esquemas de entrada claros utilizando Zod para herramientas.\n* Maneje los errores con elegancia dentro de `execute` / `read` y devuelva respuestas de error formateadas usando `formatErrorResponse` (o arroje errores).\n* Utilice la configuración centralizada ( `src/config.ts` ) a través de `getConfig()` cuando sea necesario.\n* Aproveche los inicializadores de servicio en `src/services/` para dependencias como conexiones de base de datos.\n* Agregue registro ( `console.error` ) para mayor visibilidad.","Spanish","es-ES",{"_29":48,"_33":52,"_38":53},{"_31":49,"_33":50,"_35":51},"PostgreSQL、DuckDB、Google Cloud Storage Parquet ファイルなどのデータベースと対話するためのツールを提供するモデルコンテキストプロトコルサーバー。","MCP データベースサーバー","# MCP データベースサーバー\n\n`mcp-framework`を使用して構築されたモデルコンテキストプロトコル (MCP) サーバー。データベース (DuckDB 経由の PostgreSQL) および Google Cloud Storage (GCS) と対話するためのツールとリソースを提供します。\n\n## 前提条件\n\n* Node.js 22以上\n* タイプスクリプト\n* PostgreSQL（データベース機能に必要）\n* Google Cloud 認証情報（オプション、GCS 機能用）\n* [Devbox](https://www.jetpack.io/devbox/) （ `make`コマンドを使用したローカル開発用）\n\n## プロジェクト構造\n\n```plaintext\n.\n├── docs\n│ ├── assets\n│ │ └── etl.png\n│ ├── etl-workflow.md\n│ └── setup-with-claude-desktop.md\n├── migrations\n│ ├── 1743322886782_initial-schema.cjs\n│ └── 1743323460433_continuous-aggregates.cjs\n├── scripts\n│ └── setup-continuous-aggregates.sql\n├── src\n│ ├── resources # MCP Resource definitions\n│ │ ├── gcs_objects.ts\n│ │ └── sql_tables.ts\n│ ├── services # Service initializers (DB connections, GCS client)\n│ │ ├── duckdb.ts\n│ │ ├── gcs.ts\n│ │ └── postgres.ts\n│ ├── tools # MCP Tool definitions\n│ │ ├── duckdb_insert.ts\n│ │ ├── duckdb_query.ts\n│ │ ├── duckdb_read_parquet.ts\n│ │ └── gcs_directory_tree.ts\n│ ├── utils # Utility functions (logging, formatting)\n│ │ ├── index.ts\n│ │ └── logger.ts\n│ ├── config.ts # Configuration loading and validation\n│ ├── index.ts # Main server entry point\n│ └── utils.ts # Deprecated utils? (Consider removing if unused)\n├── .env.example # Example environment variables\n├── .gitignore\n├── CLAUDE.md\n├── Dockerfile\n├── MIGRATION.md\n├── Makefile # Development commands\n├── README.md\n├── database.json # Migration configuration\n├── devbox.json # Devbox configuration\n├── devbox.lock\n├── docker-compose.yml # Docker setup for DBs\n├── fly.toml # Fly.io deployment config\n├── package-lock.json\n├── package.json\n└── tsconfig.json\n```\n\n## インストール\n\n1. リポジトリをクローンします。\n\n ```bash\n git clone \n cd mcp-db\n ```\n\n2. 依存関係をインストールします (一貫性を保つために Devbox の使用をお勧めします)。\n\n ```bash\n devbox install\n # Or using npm directly if not using Devbox\n # npm install\n ```\n\n3. `.env.example`を`.env`にコピーし、環境変数を入力します。\n\n ```bash\n cp .env.example .env\n # Edit .env with your details\n ```\n\n4. プロジェクトをビルドします。\n\n ```bash\n # Using make (requires Devbox)\n make build\n # Or using npm directly\n # npm run build\n ```\n\n## 構成\n\n### 環境変数\n\n次の環境変数 (またはコマンドライン引数) を使用してサーバーを構成します。\n\n* `DATABASE_URL` : PostgreSQL 接続文字列 (supergateway で実行しない限り必須)。\n* `DATABASE_URLS` : 複数のデータベース接続の`alias=url`ペアのコンマ区切りリスト ( `DATABASE_URL`の代替)。\n* `LOG_LEVEL` : ログレベル（ `debug` 、 `info` 、 `error` ）。デフォルト: `info` 。\n* `GCS_BUCKET` : デフォルトの Google Cloud Storage バケット名 (オプション)。\n* `GCP_SERVICE_ACCOUNT` : Base64 でエンコードされた Google Cloud サービスアカウントキー JSON (オプション、GCS 認証用)。\n* `GCS_KEY_ID` / `GCS_SECRET` : DuckDB の`httpfs`拡張機能専用の代替 GCS 認証情報 (オプション)。\n* `TRANSPORT` : トランスポートタイプ（ `stdio`または`sse` ）。デフォルト: `stdio` 。\n* `PORT` : SSEトランスポートのポート番号。デフォルト: `3001` 。\n* `HOST` : SSEトランスポートのホスト名。デフォルト: `localhost` 。\n* `API_KEY` : サーバーを保護するためのオプションの API キー (設定されている場合、クライアントは`Authorization: Bearer `ヘッダーでそれを提供する必要があります)。\n\nコマンドライン引数（例： `--port 8080` 、 `--gcs-bucket my-bucket` ）は環境変数を上書きします。詳細は`src/config.ts`を参照してください。\n\n## データベースの移行\n\nこのプロジェクトでは、PostgreSQLのスキーマ変更の管理に`node-pg-migrate`使用しています。マイグレーションの実行と作成の詳細については、上記の元のREADMEの「データベースマイグレーション」セクションをご覧ください。\n\n\\*\\*注:\\*\\*前述の`npm run setup:db`コマンドは、現在の設定に基づいて確認または更新する必要がある場合があります。\n\n## サーバーの実行\n\n便利な開発コマンドには`Makefile`を使用します (Devbox が必要です)。\n\n```bash\n# Run in development mode (builds and starts with nodemon for auto-restarts)\n# Uses SSE transport by default on port 3001\nmake dev\n\n# Run tests (if configured)\n# make test\n\n# Build for production\n# make build\n```\n\n`make`なしで実行するには ( `npm run build`の後):\n\n```bash\n# Run with stdio transport\nnode dist/index.js --transport stdio\n\n# Run with SSE transport on default port 3001\nnode dist/index.js --transport sse\n\n# Run with SSE on a different port\nnode dist/index.js --transport sse --port 8080\n```\n\n### クライアント構成\n\nMCP クライアント (例: `mcp-cli` 、Claude Desktop) をローカルサーバーに接続するには:\n\n**SSE トランスポートの場合 (例: ポート 3001):**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"sse\",\n \"--port\", \"3001\" // Match the port the server is running on\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n*(注: 以前の README の Docker/supergateway の例は古くなっているか、別のデプロイメント設定に固有のものである可能性があります。)*\n\n**Stdio トランスポートの場合:**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"stdio\"\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n### GitHubからnpxを実行する\n\nnpx を使用してサーバーを直接実行できます (パッケージ内のビルドステップが必要です)。\n\n```bash\n# Ensure required env vars are set\nexport DATABASE_URL=\"postgresql://user:password@localhost:5432/db\"\nexport GCS_BUCKET=\"my-bucket\"\n\nnpx github:dwarvesf/mcp-db --transport sse --port 3001\n```\n\n## 利用可能なツール\n\n* `duckdb_insert` : DuckDBを介して接続されたPostgreSQLデータベースに対して`INSERT`文を実行します。INSERT `INSERT`のみが許可されます。\n* `duckdb_query` : DuckDBの`postgres_query`関数を使用して、接続されたPostgreSQLデータベース（ `postgres_db` ）に対して読み取り専用のSQLクエリを直接実行します。修飾されていないテーブル名には自動的にプレフィックスが付けられます（例： `my_table``postgres_db.public.my_table`になります）。\n* `duckdb_read_parquet` : DuckDB を使用して (設定されている場合は GCS から) Parquet ファイルをクエリします。\n* `duckdb_update` : DuckDB を介して接続された PostgreSQL データベースに対して`UPDATE`ステートメントを実行します。\n* `gcs_directory_tree` : ページ区切りをサポートする GCS バケットからディレクトリツリー構造を取得します。\n\n## 利用可能なリソース\n\n* `mcp://gcs/objects` : 設定された GCS バケット内のオブジェクトを一覧表示します。\n* `mcp://db/tables` : 構成された PostgreSQL データベース内のすべてのテーブルとその列を一覧表示します。\n\n## 開発：新しいツール/リソースの統合\n\nこのプロジェクトは`mcp-framework`を使用しています。新しいツールまたはリソースを追加するには:\n\n1. **クラスを作成します:**\n\n * `src/tools/`または`src/resources/`に新しい`.ts`ファイルを作成します。\n * `MCPTool`または`MCPResource`を拡張するクラスを定義します。\n * 必要なプロパティ (ツールの場合は`name` 、 `description` 、 `schema` ) とメソッド (ツールの場合は`execute` 、リソースの場合は`read` ) を実装します。\n * 入力検証 (ツール) には、 `schema`プロパティで Zod を使用します。\n * クラス内の依存関係 (DB 接続や GCS クライアントなど) を初期化します。多くの場合、コンストラクター内で、 `src/services/`のサービスまたは`src/config.ts`の構成を使用する可能性があります。\n\n *サンプルツール ( `src/tools/my_tool.ts` ):*\n\n ```typescript\n import { MCPTool } from \"mcp-framework\";\n import { z } from \"zod\";\n import { formatSuccessResponse } from \"../utils.js\";\n import { getDuckDBConnection } from \"../services/duckdb.js\"; // Example dependency\n\n const MyToolInputSchema = z.object({\n param1: z.string().describe(\"Description for parameter 1\"),\n });\n type MyToolInput = z.infer;\n\n export class MyTool extends MCPTool {\n name = \"my_tool\";\n description = \"Description of what my tool does.\";\n schema = { // Matches Zod schema structure\n param1: { type: z.string(), description: \"Description for parameter 1\" },\n };\n\n async execute(args: MyToolInput): Promise {\n console.error(`Handling tool request: ${this.name}`);\n const duckDBConn = getDuckDBConnection(); // Get dependency\n // ... implement logic using args and duckDBConn ...\n const result = { message: `Processed ${args.param1}` };\n return formatSuccessResponse(result);\n }\n }\n export default MyTool; // Ensure default export\n ```\n\n2. **自動検出:**\n\n * `mcp-framework``src/tools`および`src/resources`ディレクトリ内のファイルからデフォルトでエクスポートされるツール/リソースクラスを自動的に検出して登録します。\n * 新しいクラスがファイル内の`default export`であることを確認します。\n\n3. **テスト：**\n\n * サーバーを実行します ( `make dev` )。\n * 起動ログをチェックして、新しいツール/リソースがリストされていることを確認します。\n * MCP クライアント ( `mcp-cli`や MCP Inspector など) を使用してツールを呼び出すか、リソースを読み取ってその機能を検証します。\n\n### ベストプラクティス\n\n* ツール用の Zod を使用して明確な入力スキーマを定義します。\n* `execute` / `read`内でエラーを適切に処理し、 `formatErrorResponse`を使用してフォーマットされたエラー応答を返します (またはエラーをスローします)。\n* 必要に応じて、 `getConfig()`を介して集中構成 ( `src/config.ts` ) を使用します。\n* データベース接続などの依存関係には、 `src/services/`内のサービス初期化子を活用します。\n* 可視性のためにログ ( `console.error` ) を追加します。","Japanese","ja-JP",{"_29":55,"_33":59,"_38":60},{"_31":56,"_33":57,"_35":58},"PostgreSQL, DuckDB, Google Cloud Storage Parquet 파일을 포함한 데이터베이스와 상호 작용하기 위한 도구를 제공하는 모델 컨텍스트 프로토콜 서버입니다.","MCP 데이터베이스 서버","# MCP 데이터베이스 서버\n\n`mcp-framework` 로 구축된 MCP(Model Context Protocol) 서버는 데이터베이스(DuckDB를 통한 PostgreSQL) 및 Google Cloud Storage(GCS)와 상호작용하기 위한 도구와 리소스를 제공합니다.\n\n## 필수 조건\n\n* Node.js 22 이상\n* 타입스크립트\n* PostgreSQL(데이터베이스 기능에 필요)\n* Google Cloud 자격 증명(선택 사항, GCS 기능용)\n* [Devbox](https://www.jetpack.io/devbox/) ( `make` 명령을 사용한 로컬 개발용)\n\n## 프로젝트 구조\n\n지엑스피1\n\n## 설치\n\n1. 저장소를 복제합니다.\n\n ```bash\n git clone \n cd mcp-db\n ```\n\n2. 종속성 설치(일관성을 위해 Devbox 사용이 권장됨):\n\n ```bash\n devbox install\n # Or using npm directly if not using Devbox\n # npm install\n ```\n\n3. `.env.example``.env` 로 복사하고 환경 변수를 입력합니다.\n\n ```bash\n cp .env.example .env\n # Edit .env with your details\n ```\n\n4. 프로젝트를 빌드하세요:\n\n ```bash\n # Using make (requires Devbox)\n make build\n # Or using npm directly\n # npm run build\n ```\n\n## 구성\n\n### 환경 변수\n\n다음 환경 변수(또는 명령줄 인수)를 사용하여 서버를 구성합니다.\n\n* `DATABASE_URL` : PostgreSQL 연결 문자열(supergateway로 실행하지 않는 한 필수).\n* `DATABASE_URLS` : 여러 데이터베이스 연결에 대한 `alias=url` 쌍의 쉼표로 구분된 목록( `DATABASE_URL` 의 대안).\n* `LOG_LEVEL` : 로깅 수준( `debug` , `info` , `error` ). 기본값: `info` .\n* `GCS_BUCKET` : 기본 Google Cloud Storage 버킷 이름(선택 사항).\n* `GCP_SERVICE_ACCOUNT` : Base64로 인코딩된 Google Cloud 서비스 계정 키 JSON(선택 사항, GCS 인증용).\n* `GCS_KEY_ID` / `GCS_SECRET` : DuckDB의 `httpfs` 확장을 위한 대체 GCS 자격 증명(선택 사항).\n* `TRANSPORT` : 전송 유형( `stdio` 또는 `sse` ). 기본값: `stdio` .\n* `PORT` : SSE 전송을 위한 포트 번호. 기본값: `3001` .\n* `HOST` : SSE 전송 호스트 이름입니다. 기본값: `localhost` .\n* `API_KEY` : 서버를 보호하기 위한 선택적 API 키(설정된 경우 클라이언트가 `Authorization: Bearer ` 헤더에서 제공해야 함).\n\n명령줄 인수(예: `--port 8080` , `--gcs-bucket my-bucket` )는 환경 변수보다 우선합니다. 자세한 내용은 `src/config.ts` 참조하세요.\n\n## 데이터베이스 마이그레이션\n\n이 프로젝트는 PostgreSQL 스키마 변경 관리를 위해 `node-pg-migrate` 사용합니다. 마이그레이션 실행 및 생성에 대한 자세한 내용은 위 README 원본의 \"데이터베이스 마이그레이션\" 섹션을 참조하세요.\n\n**참고:** 이전에 언급한 `npm run setup:db` 명령은 현재 설정에 따라 검토 또는 업데이트가 필요할 수 있습니다.\n\n## 서버 실행\n\n편리한 개발 명령을 위해 `Makefile` 사용하세요(Devbox 필요):\n\n```bash\n# Run in development mode (builds and starts with nodemon for auto-restarts)\n# Uses SSE transport by default on port 3001\nmake dev\n\n# Run tests (if configured)\n# make test\n\n# Build for production\n# make build\n```\n\n`make` 없이 실행하려면( `npm run build` 후):\n\n```bash\n# Run with stdio transport\nnode dist/index.js --transport stdio\n\n# Run with SSE transport on default port 3001\nnode dist/index.js --transport sse\n\n# Run with SSE on a different port\nnode dist/index.js --transport sse --port 8080\n```\n\n### 클라이언트 구성\n\nMCP 클라이언트(예: `mcp-cli` , Claude Desktop)를 로컬 서버에 연결하려면:\n\n**SSE 전송의 경우(예: 포트 3001):**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"sse\",\n \"--port\", \"3001\" // Match the port the server is running on\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n*(참고: 이전 README의 Docker/supergateway 예제는 오래되었거나 다른 배포 설정에만 해당될 수 있습니다.)*\n\n**Stdio Transport의 경우:**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"stdio\"\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n### GitHub에서 npx로 실행\n\nnpx를 사용하여 서버를 직접 실행할 수 있습니다(패키지의 빌드 단계 필요):\n\n```bash\n# Ensure required env vars are set\nexport DATABASE_URL=\"postgresql://user:password@localhost:5432/db\"\nexport GCS_BUCKET=\"my-bucket\"\n\nnpx github:dwarvesf/mcp-db --transport sse --port 3001\n```\n\n## 사용 가능한 도구\n\n* `duckdb_insert` : DuckDB를 통해 연결된 PostgreSQL 데이터베이스에 `INSERT` 문을 실행합니다. `INSERT` 쿼리만 허용됩니다.\n* `duckdb_query` : DuckDB의 `postgres_query` 함수를 사용하여 연결된 PostgreSQL 데이터베이스( `postgres_db` )에 직접 읽기 전용 SQL 쿼리를 실행합니다. 정규화되지 않은 테이블 이름에 자동으로 접두사를 붙입니다(예: `my_table``postgres_db.public.my_table` 이 됩니다).\n* `duckdb_read_parquet` : DuckDB를 사용하여 Parquet 파일을 쿼리합니다(구성된 경우 GCS에서).\n* `duckdb_update` : DuckDB를 통해 연결된 PostgreSQL 데이터베이스에 `UPDATE` 문을 실행합니다.\n* `gcs_directory_tree` : 페이지 분할을 지원하는 GCS 버킷에서 디렉토리 트리 구조를 가져옵니다.\n\n## 사용 가능한 리소스\n\n* `mcp://gcs/objects` : 구성된 GCS 버킷에 있는 객체를 나열합니다.\n* `mcp://db/tables` : 구성된 PostgreSQL 데이터베이스에 있는 모든 테이블과 열을 나열합니다.\n\n## 개발: 새로운 도구/리소스 통합\n\n이 프로젝트에서는 `mcp-framework` 사용합니다. 새 도구나 리소스를 추가하려면 다음을 수행하세요.\n\n1. **클래스 만들기:**\n\n * `src/tools/` 또는 `src/resources/` 에 새로운 `.ts` 파일을 만듭니다.\n * `MCPTool` 또는 `MCPResource` 확장하는 클래스를 정의합니다.\n * 필요한 속성(도구의 경우 `name` , `description` , `schema` )과 메서드(도구의 경우 `execute` , 리소스의 경우 `read` )를 구현합니다.\n * 입력 검증(도구)을 위해 `schema` 속성에서 Zod를 사용합니다.\n * 클래스 내에서(종종 생성자 내에서) 모든 종속성(DB 연결이나 GCS 클라이언트)을 초기화하는데, `src/services/` 의 서비스나 `src/config.ts` 의 구성을 사용할 가능성이 있습니다.\n\n *예제 도구( `src/tools/my_tool.ts` ):*\n\n ```typescript\n import { MCPTool } from \"mcp-framework\";\n import { z } from \"zod\";\n import { formatSuccessResponse } from \"../utils.js\";\n import { getDuckDBConnection } from \"../services/duckdb.js\"; // Example dependency\n\n const MyToolInputSchema = z.object({\n param1: z.string().describe(\"Description for parameter 1\"),\n });\n type MyToolInput = z.infer;\n\n export class MyTool extends MCPTool {\n name = \"my_tool\";\n description = \"Description of what my tool does.\";\n schema = { // Matches Zod schema structure\n param1: { type: z.string(), description: \"Description for parameter 1\" },\n };\n\n async execute(args: MyToolInput): Promise {\n console.error(`Handling tool request: ${this.name}`);\n const duckDBConn = getDuckDBConnection(); // Get dependency\n // ... implement logic using args and duckDBConn ...\n const result = { message: `Processed ${args.param1}` };\n return formatSuccessResponse(result);\n }\n }\n export default MyTool; // Ensure default export\n ```\n\n2. **자동 검색:**\n\n * `mcp-framework``src/tools` 및 `src/resources` 디렉토리에 있는 파일에서 기본적으로 내보내진 도구/리소스 클래스를 자동으로 검색하여 등록합니다.\n * 새 클래스가 해당 파일에서 `default export` 설정되어 있는지 확인하세요.\n\n3. **시험:**\n\n * 서버를 실행합니다( `make dev` ).\n * 시작 로그를 확인하여 새 도구/리소스가 나열되어 있는지 확인하세요.\n * MCP 클라이언트( `mcp-cli` 또는 MCP Inspector 등)를 사용하여 도구를 호출하거나 리소스를 읽고 기능을 확인합니다.\n\n### 모범 사례\n\n* 도구용 Zod를 사용하여 명확한 입력 스키마를 정의합니다.\n* `execute` / `read` 내에서 오류를 우아하게 처리하고 `formatErrorResponse` (또는 오류 발생)를 사용하여 형식화된 오류 응답을 반환합니다.\n* 필요한 경우 `getConfig()` 를 통해 중앙화된 구성( `src/config.ts` )을 사용합니다.\n* 데이터베이스 연결과 같은 종속성을 위해 `src/services/` 에 있는 서비스 초기화 프로그램을 활용합니다.\n* 가시성을 위해 로깅( `console.error` )을 추가합니다.","Korean","ko-KR",{"_29":62,"_33":66,"_38":67},{"_31":63,"_33":64,"_35":65},"模型上下文协议服务器提供与数据库交互的工具，包括 PostgreSQL、DuckDB 和 Google Cloud Storage Parquet 文件。","MCP 数据库服务器","# MCP 数据库服务器\n\n使用`mcp-framework`构建的模型上下文协议 (MCP) 服务器，提供与数据库（通过 DuckDB 的 PostgreSQL）和 Google Cloud Storage（GCS）交互的工具和资源。\n\n## 先决条件\n\n* Node.js 22 或更高版本\n* TypeScript\n* PostgreSQL（数据库功能所需）\n* Google Cloud 凭据（可选，用于 GCS 功能）\n* [Devbox](https://www.jetpack.io/devbox/) （使用`make`命令进行本地开发）\n\n## 项目结构\n\n```plaintext\n.\n├── docs\n│ ├── assets\n│ │ └── etl.png\n│ ├── etl-workflow.md\n│ └── setup-with-claude-desktop.md\n├── migrations\n│ ├── 1743322886782_initial-schema.cjs\n│ └── 1743323460433_continuous-aggregates.cjs\n├── scripts\n│ └── setup-continuous-aggregates.sql\n├── src\n│ ├── resources # MCP Resource definitions\n│ │ ├── gcs_objects.ts\n│ │ └── sql_tables.ts\n│ ├── services # Service initializers (DB connections, GCS client)\n│ │ ├── duckdb.ts\n│ │ ├── gcs.ts\n│ │ └── postgres.ts\n│ ├── tools # MCP Tool definitions\n│ │ ├── duckdb_insert.ts\n│ │ ├── duckdb_query.ts\n│ │ ├── duckdb_read_parquet.ts\n│ │ └── gcs_directory_tree.ts\n│ ├── utils # Utility functions (logging, formatting)\n│ │ ├── index.ts\n│ │ └── logger.ts\n│ ├── config.ts # Configuration loading and validation\n│ ├── index.ts # Main server entry point\n│ └── utils.ts # Deprecated utils? (Consider removing if unused)\n├── .env.example # Example environment variables\n├── .gitignore\n├── CLAUDE.md\n├── Dockerfile\n├── MIGRATION.md\n├── Makefile # Development commands\n├── README.md\n├── database.json # Migration configuration\n├── devbox.json # Devbox configuration\n├── devbox.lock\n├── docker-compose.yml # Docker setup for DBs\n├── fly.toml # Fly.io deployment config\n├── package-lock.json\n├── package.json\n└── tsconfig.json\n```\n\n## 安装\n\n1. 克隆存储库：\n\n ```bash\n git clone \n cd mcp-db\n ```\n\n2. 安装依赖项（建议使用 Devbox 以确保一致性）：\n\n ```bash\n devbox install\n # Or using npm directly if not using Devbox\n # npm install\n ```\n\n3. 将`.env.example`复制到`.env`并填写您的环境变量。\n\n ```bash\n cp .env.example .env\n # Edit .env with your details\n ```\n\n4. 构建项目：\n\n ```bash\n # Using make (requires Devbox)\n make build\n # Or using npm directly\n # npm run build\n ```\n\n## 配置\n\n### 环境变量\n\n使用这些环境变量（或命令行参数）配置服务器：\n\n* `DATABASE_URL` ：PostgreSQL 连接字符串（除非使用超级网关运行，否则是必需的）。\n* `DATABASE_URLS` ：用于多个数据库连接的`alias=url`对的逗号分隔列表（ `DATABASE_URL`的替代）。\n* `LOG_LEVEL` ：日志级别（ `debug` 、 `info` 、 `error` ）。默认值： `info` 。\n* `GCS_BUCKET` ：默认 Google Cloud Storage 存储桶名称（可选）。\n* `GCP_SERVICE_ACCOUNT` ：Base64 编码的 Google Cloud 服务帐户密钥 JSON（可选，用于 GCS 身份验证）。\n* `GCS_KEY_ID` / `GCS_SECRET` ：专门用于 DuckDB 的`httpfs`扩展的替代 GCS 凭证（可选）。\n* `TRANSPORT` ：传输类型（ `stdio`或`sse` ）。默认值： `stdio` 。\n* `PORT` ：SSE 传输的端口号。默认值： `3001` 。\n* `HOST` ：SSE 传输的主机名。默认值： `localhost` 。\n* `API_KEY` ：用于保护服务器的可选 API 密钥（如果设置，客户端必须在`Authorization: Bearer `标头中提供它）。\n\n命令行参数（例如`--port 8080` 、 `--gcs-bucket my-bucket` ）会覆盖环境变量。详情请参阅`src/config.ts` 。\n\n## 数据库迁移\n\n该项目使用`node-pg-migrate`来管理 PostgreSQL 数据库架构变更。有关运行和创建迁移的详细信息，请参阅上文原始 README 文件中的“数据库迁移”部分。\n\n\\*\\*注意：\\*\\*前面提到的`npm run setup:db`命令可能需要根据当前设置进行审查或更新。\n\n## 运行服务器\n\n使用`Makefile`进行便捷的开发命令（需要 Devbox）：\n\n```bash\n# Run in development mode (builds and starts with nodemon for auto-restarts)\n# Uses SSE transport by default on port 3001\nmake dev\n\n# Run tests (if configured)\n# make test\n\n# Build for production\n# make build\n```\n\n不使用`make`运行（在`npm run build`之后）：\n\n```bash\n# Run with stdio transport\nnode dist/index.js --transport stdio\n\n# Run with SSE transport on default port 3001\nnode dist/index.js --transport sse\n\n# Run with SSE on a different port\nnode dist/index.js --transport sse --port 8080\n```\n\n### 客户端配置\n\n要将您的 MCP 客户端（例如`mcp-cli` 、Claude Desktop）连接到本地服务器：\n\n**对于 SSE 传输（例如，在端口 3001 上）：**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"sse\",\n \"--port\", \"3001\" // Match the port the server is running on\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n*（注意：上一个 README 中的 Docker/supergateway 示例可能已过时或特定于不同的部署设置。）*\n\n**对于 Stdio 传输：**\n\n```json\n{\n \"mcpServers\": {\n \"mcp-db-local\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-db/dist/index.js\", // Adjust path if needed\n \"--transport\", \"stdio\"\n ],\n // Add \"env\" if API_KEY is set\n // \"env\": { \"API_KEY\": \"your-secret-key\" }\n }\n }\n}\n```\n\n### 使用 GitHub 上的 npx 运行\n\n您可以使用 npx 直接运行服务器（需要包中的构建步骤）：\n\n```bash\n# Ensure required env vars are set\nexport DATABASE_URL=\"postgresql://user:password@localhost:5432/db\"\nexport GCS_BUCKET=\"my-bucket\"\n\nnpx github:dwarvesf/mcp-db --transport sse --port 3001\n```\n\n## 可用工具\n\n* `duckdb_insert` ：通过 DuckDB 在附加的 PostgreSQL 数据库上执行`INSERT`语句。仅允许`INSERT`查询。\n* `duckdb_query` ：使用 DuckDB 的`postgres_query`函数直接在连接的 PostgreSQL 数据库 ( `postgres_db` ) 上执行只读 SQL 查询。会自动为非限定表名添加前缀（例如， `my_table`变为`postgres_db.public.my_table` ）。\n* `duckdb_read_parquet` ：使用 DuckDB 查询 Parquet 文件（如果配置的话，可能从 GCS 查询）。\n* `duckdb_update` ：通过 DuckDB 对附加的 PostgreSQL 数据库执行`UPDATE`语句。\n* `gcs_directory_tree` ：从支持分页的 GCS 存储桶中获取目录树结构。\n\n## 可用资源\n\n* `mcp://gcs/objects` ：列出配置的 GCS 存储桶中的对象。\n* `mcp://db/tables` ：列出配置的 PostgreSQL 数据库中的所有表及其列。\n\n## 开发：整合新工具/资源\n\n本项目使用`mcp-framework` 。要添加新工具或资源，请执行以下操作：\n\n1. **创建类：**\n\n * 在`src/tools/`或`src/resources/`中创建一个新的`.ts`文件。\n * 定义一个扩展`MCPTool`或`MCPResource`类。\n * 实现所需的属性（工具的`name` 、 `description` 、 `schema` ）和方法（工具的`execute` 、资源的`read` ）。\n * 在`schema`属性中使用 Zod 进行输入验证（工具）。\n * 初始化类中的任何依赖项（如 DB 连接或 GCS 客户端），通常在构造函数中，可能使用来自`src/services/`服务或来自`src/config.ts`的配置。\n\n *示例工具（ `src/tools/my_tool.ts` ）：*\n\n ```typescript\n import { MCPTool } from \"mcp-framework\";\n import { z } from \"zod\";\n import { formatSuccessResponse } from \"../utils.js\";\n import { getDuckDBConnection } from \"../services/duckdb.js\"; // Example dependency\n\n const MyToolInputSchema = z.object({\n param1: z.string().describe(\"Description for parameter 1\"),\n });\n type MyToolInput = z.infer;\n\n export class MyTool extends MCPTool {\n name = \"my_tool\";\n description = \"Description of what my tool does.\";\n schema = { // Matches Zod schema structure\n param1: { type: z.string(), description: \"Description for parameter 1\" },\n };\n\n async execute(args: MyToolInput): Promise {\n console.error(`Handling tool request: ${this.name}`);\n const duckDBConn = getDuckDBConnection(); // Get dependency\n // ... implement logic using args and duckDBConn ...\n const result = { message: `Processed ${args.param1}` };\n return formatSuccessResponse(result);\n }\n }\n export default MyTool; // Ensure default export\n ```\n\n2. **自动发现：**\n\n * `mcp-framework`自动发现并注册从`src/tools`和`src/resources`目录中的文件默认导出的工具/资源类。\n * 确保您的新类是其文件中的`default export` 。\n\n3. **测试：**\n\n * 运行服务器（ `make dev` ）。\n * 检查启动日志以确保列出了您的新工具/资源。\n * 使用 MCP 客户端（如`mcp-cli`或 MCP Inspector）调用该工具或读取资源并验证其功能。\n\n### 最佳实践\n\n* 使用 Zod 为工具定义清晰的输入模式。\n* 在`execute` / `read`过程中优雅地处理错误，并使用`formatErrorResponse`返回格式化的错误响应（或抛出错误）。\n* 在需要的地方通过`getConfig()`使用集中配置（ `src/config.ts` ）。\n* 利用`src/services/`中的服务初始化程序来实现数据库连接等依赖项。\n* 添加日志记录（ `console.error` ）以提高可见性。","Chinese","zh-CN","githubUser","locale",{"_71":72,"_73":74,"_13":93,"_96":32,"_97":32,"_98":99,"_102":103,"_124":-5,"_16":125,"_126":127,"_128":129,"_33":34,"_154":116,"_155":-5,"_156":-5,"_157":-5,"_158":-5,"_159":160,"_164":-5,"_136":112,"_165":166,"_170":-5,"_117":171,"_172":173},"addedAt",["D",1742574246562],"argumentsJsonSchema",{"_75":76,"_90":91,"_82":92},"properties",{"_77":78,"_84":85,"_87":88},"LOG_LEVEL",{"_79":80,"_31":81,"_82":83},"default","info","Logging level (debug, info, error)","type","string","DATABASE_URL",{"_31":86,"_82":83},"PostgreSQL connection string","GCP_SERVICE_ACCOUNT",{"_31":89,"_82":83},"Google Cloud service account credentials (base64-encoded, for GCS access)","required",[84],"object",[94,95],"language:typescript","license_grade:f","descriptionMarkdown","descriptionPlainText","githubProject",{"_35":36,"_100":101},"url","https://github.com/dwarvesf/mcp-db","githubRepository",{"_104":105,"_106":107,"_108":109,"_110":111,"_33":112,"_113":114,"_119":120,"_121":-5,"_122":123},"defaultBranch","main","fullName","dwarvesf/mcp-db","githubTreeId",111095,"language","TypeScript","mcp-db","owner",{"_115":116,"_117":118},"login","dwarvesf","uid","QiezL7c4os","recentStargazers",0,"spdxLicense","stargazers",2,"glamaJson",2666,"inspectable",false,"integrations",[130,140,147],{"_131":132,"_31":138,"_117":139},"brand",{"_133":134,"_33":135,"_136":137},"logoSvgPath","M12 0C5.363 0 0 5.363 0 12s5.363 12 12 12 12-5.363 12-12S18.637 0 12 0zM9.502 7.03a4.974 4.974 0 0 1 4.97 4.97 4.974 4.974 0 0 1-4.97 4.97A4.974 4.974 0 0 1 4.532 12a4.974 4.974 0 0 1 4.97-4.97zm6.563 3.183h2.351c.98 0 1.787.782 1.787 1.762s-.807 1.789-1.787 1.789h-2.351v-3.551z","DuckDB","slug","duckdb","Enables querying Parquet files through DuckDB, providing data analysis capabilities on structured files","zguk16bmmm",{"_131":141,"_31":145,"_117":146},{"_133":142,"_33":143,"_136":144},"M24 2.4v8.4h-2.4V2.4H24zM0 10.8h2.4V2.4H0v8.4zm3-8.4h18v8.4H3V2.4zm12.6 4.2a1.8 1.8 0 1 0 3.6 0 1.8 1.8 0 0 0-3.6 0zm-10.8.6H12V6H4.8v1.2zm16.8 14.4H24v-8.4h-2.4v8.4zM0 21.6h2.4v-8.4H0v8.4zm3-8.4h18v8.4H3v-8.4zm12.6 4.2a1.8 1.8 0 1 0 3.6 0 1.8 1.8 0 0 0-3.6 0zM4.8 18H12v-1.2H4.8V18z","Google Cloud Storage","google-cloud-storage","Allows reading and querying Parquet files stored in Google Cloud Storage buckets","daax4l93n3",{"_131":148,"_31":152,"_117":153},{"_133":149,"_33":150,"_136":151},"M23.5594 14.7228a.5269.5269 0 0 0-.0563-.1191c-.139-.2632-.4768-.3418-1.0074-.2321-1.6533.3411-2.2935.1312-2.5256-.0191 1.342-2.0482 2.445-4.522 3.0411-6.8297.2714-1.0507.7982-3.5237.1222-4.7316a1.5641 1.5641 0 0 0-.1509-.235C21.6931.9086 19.8007.0248 17.5099.0005c-1.4947-.0158-2.7705.3461-3.1161.4794a9.449 9.449 0 0 0-.5159-.0816 8.044 8.044 0 0 0-1.3114-.1278c-1.1822-.0184-2.2038.2642-3.0498.8406-.8573-.3211-4.7888-1.645-7.2219.0788C.9359 2.1526.3086 3.8733.4302 6.3043c.0409.818.5069 3.334 1.2423 5.7436.4598 1.5065.9387 2.7019 1.4334 3.582.553.9942 1.1259 1.5933 1.7143 1.7895.4474.1491 1.1327.1441 1.8581-.7279.8012-.9635 1.5903-1.8258 1.9446-2.2069.4351.2355.9064.3625 1.39.3772a.0569.0569 0 0 0 .0004.0041 11.0312 11.0312 0 0 0-.2472.3054c-.3389.4302-.4094.5197-1.5002.7443-.3102.064-1.1344.2339-1.1464.8115-.0025.1224.0329.2309.0919.3268.2269.4231.9216.6097 1.015.6331 1.3345.3335 2.5044.092 3.3714-.6787-.017 2.231.0775 4.4174.3454 5.0874.2212.5529.7618 1.9045 2.4692 1.9043.2505 0 .5263-.0291.8296-.0941 1.7819-.3821 2.5557-1.1696 2.855-2.9059.1503-.8707.4016-2.8753.5388-4.1012.0169-.0703.0357-.1207.057-.1362.0007-.0005.0697-.0471.4272.0307a.3673.3673 0 0 0 .0443.0068l.2539.0223.0149.001c.8468.0384 1.9114-.1426 2.5312-.4308.6438-.2988 1.8057-1.0323 1.5951-1.6698zM2.371 11.8765c-.7435-2.4358-1.1779-4.8851-1.2123-5.5719-.1086-2.1714.4171-3.6829 1.5623-4.4927 1.8367-1.2986 4.8398-.5408 6.108-.13-.0032.0032-.0066.0061-.0098.0094-2.0238 2.044-1.9758 5.536-1.9708 5.7495-.0002.0823.0066.1989.0162.3593.0348.5873.0996 1.6804-.0735 2.9184-.1609 1.1504.1937 2.2764.9728 3.0892.0806.0841.1648.1631.2518.2374-.3468.3714-1.1004 1.1926-1.9025 2.1576-.5677.6825-.9597.5517-1.0886.5087-.3919-.1307-.813-.5871-1.2381-1.3223-.4796-.839-.9635-2.0317-1.4155-3.5126zm6.0072 5.0871c-.1711-.0428-.3271-.1132-.4322-.1772.0889-.0394.2374-.0902.4833-.1409 1.2833-.2641 1.4815-.4506 1.9143-1.0002.0992-.126.2116-.2687.3673-.4426a.3549.3549 0 0 0 .0737-.1298c.1708-.1513.2724-.1099.4369-.0417.156.0646.3078.26.3695.4752.0291.1016.0619.2945-.0452.4444-.9043 1.2658-2.2216 1.2494-3.1676 1.0128zm2.094-3.988-.0525.141c-.133.3566-.2567.6881-.3334 1.003-.6674-.0021-1.3168-.2872-1.8105-.8024-.6279-.6551-.9131-1.5664-.7825-2.5004.1828-1.3079.1153-2.4468.079-3.0586-.005-.0857-.0095-.1607-.0122-.2199.2957-.2621 1.6659-.9962 2.6429-.7724.4459.1022.7176.4057.8305.928.5846 2.7038.0774 3.8307-.3302 4.7363-.084.1866-.1633.3629-.2311.5454zm7.3637 4.5725c-.0169.1768-.0358.376-.0618.5959l-.146.4383a.3547.3547 0 0 0-.0182.1077c-.0059.4747-.054.6489-.115.8693-.0634.2292-.1353.4891-.1794 1.0575-.11 1.4143-.8782 2.2267-2.4172 2.5565-1.5155.3251-1.7843-.4968-2.0212-1.2217a6.5824 6.5824 0 0 0-.0769-.2266c-.2154-.5858-.1911-1.4119-.1574-2.5551.0165-.5612-.0249-1.9013-.3302-2.6462.0044-.2932.0106-.5909.019-.8918a.3529.3529 0 0 0-.0153-.1126 1.4927 1.4927 0 0 0-.0439-.208c-.1226-.4283-.4213-.7866-.7797-.9351-.1424-.059-.4038-.1672-.7178-.0869.067-.276.1831-.5875.309-.9249l.0529-.142c.0595-.16.134-.3257.213-.5012.4265-.9476 1.0106-2.2453.3766-5.1772-.2374-1.0981-1.0304-1.6343-2.2324-1.5098-.7207.0746-1.3799.3654-1.7088.5321a5.6716 5.6716 0 0 0-.1958.1041c.0918-1.1064.4386-3.1741 1.7357-4.4823a4.0306 4.0306 0 0 1 .3033-.276.3532.3532 0 0 0 .1447-.0644c.7524-.5706 1.6945-.8506 2.802-.8325.4091.0067.8017.0339 1.1742.081 1.939.3544 3.2439 1.4468 4.0359 2.3827.8143.9623 1.2552 1.9315 1.4312 2.4543-1.3232-.1346-2.2234.1268-2.6797.779-.9926 1.4189.543 4.1729 1.2811 5.4964.1353.2426.2522.4522.2889.5413.2403.5825.5515.9713.7787 1.2552.0696.087.1372.1714.1885.245-.4008.1155-1.1208.3825-1.0552 1.717-.0123.1563-.0423.4469-.0834.8148-.0461.2077-.0702.4603-.0994.7662zm.8905-1.6211c-.0405-.8316.2691-.9185.5967-1.0105a2.8566 2.8566 0 0 0 .135-.0406 1.202 1.202 0 0 0 .1342.103c.5703.3765 1.5823.4213 3.0068.1344-.2016.1769-.5189.3994-.9533.6011-.4098.1903-1.0957.333-1.7473.3636-.7197.0336-1.0859-.0807-1.1721-.151zm.5695-9.2712c-.0059.3508-.0542.6692-.1054 1.0017-.055.3576-.112.7274-.1264 1.1762-.0142.4368.0404.8909.0932 1.3301.1066.887.216 1.8003-.2075 2.7014a3.5272 3.5272 0 0 1-.1876-.3856c-.0527-.1276-.1669-.3326-.3251-.6162-.6156-1.1041-2.0574-3.6896-1.3193-4.7446.3795-.5427 1.3408-.5661 2.1781-.463zm.2284 7.0137a12.3762 12.3762 0 0 0-.0853-.1074l-.0355-.0444c.7262-1.1995.5842-2.3862.4578-3.4385-.0519-.4318-.1009-.8396-.0885-1.2226.0129-.4061.0666-.7543.1185-1.0911.0639-.415.1288-.8443.1109-1.3505.0134-.0531.0188-.1158.0118-.1902-.0457-.4855-.5999-1.938-1.7294-3.253-.6076-.7073-1.4896-1.4972-2.6889-2.0395.5251-.1066 1.2328-.2035 2.0244-.1859 2.0515.0456 3.6746.8135 4.8242 2.2824a.908.908 0 0 1 .0667.1002c.7231 1.3556-.2762 6.2751-2.9867 10.5405zm-8.8166-6.1162c-.025.1794-.3089.4225-.6211.4225a.5821.5821 0 0 1-.0809-.0056c-.1873-.026-.3765-.144-.5059-.3156-.0458-.0605-.1203-.178-.1055-.2844.0055-.0401.0261-.0985.0925-.1488.1182-.0894.3518-.1226.6096-.0867.3163.0441.6426.1938.6113.4186zm7.9305-.4114c.0111.0792-.049.201-.1531.3102-.0683.0717-.212.1961-.4079.2232a.5456.5456 0 0 1-.075.0052c-.2935 0-.5414-.2344-.5607-.3717-.024-.1765.2641-.3106.5611-.352.297-.0414.6111.0088.6356.1851z","PostgreSQL","postgresql","Provides tools for executing SQL queries against PostgreSQL databases, including SELECT, CREATE/INSERT, UPDATE, and DELETE operations","hr1pbkbw7e","namespace","npmPackage","prompts","redditPostForeignId","resources","scores",{"_161":120,"_162":-5,"_163":-5},"license","quality","security","simpleIcon","supportedPlatforms",[167,168,169],"WINDOWS","LINUX","MACOS","tools","sq86lal1oy","updatedAt",["D",1745578857721],"meta",[176,179,181,188,191,193,196,199,202,205,208,210,213,216,218,220,222,224,226],{"_177":178},"title","MCP Database Server | Glama",{"_180":32,"_33":31},"content",{"_182":183,"_184":185,"_186":187},"href","https://glama.ai/mcp/servers/@dwarvesf/mcp-db","rel","canonical","tagName","link",{"_180":34,"_189":190},"property","og:title",{"_180":32,"_189":192},"og:description",{"_180":194,"_189":195},"https://glama.ai/logo.png","og:logo",{"_180":197,"_189":198},"https://glama.ai/mcp/servers/@dwarvesf/mcp-db/og-image","og:image",{"_180":200,"_189":201},"630","og:image:height",{"_180":203,"_189":204},"1200","og:image:width",{"_180":206,"_189":207},"website","og:type",{"_180":183,"_189":209},"og:url",{"_180":211,"_189":212},"Glama – MCP Hosting Platform","og:site_name",{"_180":214,"_33":215},"summary_large_image","twitter:card",{"_180":211,"_33":217},"twitter:title",{"_180":32,"_33":219},"twitter:description",{"_180":197,"_33":221},"twitter:image",{"_180":200,"_33":223},"twitter:image:height",{"_180":203,"_33":225},"twitter:image:width",{"_227":228},"script:ld+json",{"_229":230,"_231":232},"@context","http://schema.org","@graph",[233],{"_229":234,"_235":236,"_237":238},"https://schema.org","@type","BreadcrumbList","itemListElement",[239,246,249,253],{"_235":240,"_241":242,"_33":243,"_244":245},"ListItem","item","https://glama.ai/","Glama","position",1,{"_235":240,"_241":247,"_33":248,"_244":123},"https://glama.ai/mcp","MCP",{"_235":240,"_241":250,"_33":251,"_244":252},"https://glama.ai/mcp/servers","Servers",3,{"_235":240,"_241":183,"_33":34,"_244":254},4,"visitorIsMaintainer","routes/_public/mcp/servers/~namespace/~slug/_pages/reviews/_route",{"_68":-5,"_29":258,"_174":280,"_315":-5},{"_71":259,"_73":260,"_13":266,"_96":32,"_97":32,"_98":267,"_102":268,"_124":-5,"_16":125,"_126":127,"_128":270,"_33":34,"_154":116,"_155":-5,"_156":-5,"_157":-5,"_158":-5,"_159":277,"_164":-5,"_136":112,"_165":278,"_170":-5,"_117":171,"_172":279},["D",1742574246562],{"_75":261,"_90":265,"_82":92},{"_77":262,"_84":263,"_87":264},{"_79":80,"_31":81,"_82":83},{"_31":86,"_82":83},{"_31":89,"_82":83},[84],[94,95],{"_35":36,"_100":101},{"_104":105,"_106":107,"_108":109,"_110":111,"_33":112,"_113":269,"_119":120,"_121":-5,"_122":123},{"_115":116,"_117":118},[271,273,275],{"_131":272,"_31":138,"_117":139},{"_133":134,"_33":135,"_136":137},{"_131":274,"_31":145,"_117":146},{"_133":142,"_33":143,"_136":144},{"_131":276,"_31":152,"_117":153},{"_133":149,"_33":150,"_136":151},{"_161":120,"_162":-5,"_163":-5},[167,168,169],["D",1745578857721],[281,283,285,287,289,290,291,292,293,294,295,296,297,298,299,300,301,302,303],{"_177":282},"Reviews | MCP Database Server | Glama",{"_180":284,"_33":31},"Read community reviews and feedback for MCP Database Server. Discover user experiences, ratings, strengths, and potential limitations of this MCP implementation from actual users.",{"_182":286,"_184":185,"_186":187},"https://glama.ai/mcp/servers/@dwarvesf/mcp-db/reviews",{"_180":288,"_189":190},"Reviews | MCP Database Server",{"_180":284,"_189":192},{"_180":194,"_189":195},{"_180":197,"_189":198},{"_180":200,"_189":201},{"_180":203,"_189":204},{"_180":206,"_189":207},{"_180":286,"_189":209},{"_180":211,"_189":212},{"_180":214,"_33":215},{"_180":211,"_33":217},{"_180":284,"_33":219},{"_180":197,"_33":221},{"_180":200,"_33":223},{"_180":203,"_33":225},{"_227":304},{"_229":230,"_231":305},[306],{"_229":234,"_235":236,"_237":307},[308,309,310,311,312],{"_235":240,"_241":242,"_33":243,"_244":245},{"_235":240,"_241":247,"_33":248,"_244":123},{"_235":240,"_241":250,"_33":251,"_244":252},{"_235":240,"_241":183,"_33":34,"_244":254},{"_235":240,"_241":286,"_33":313,"_244":314},"Reviews",5,"review","actionData","errors"]

Rate & Review