feat: Add retrieve database endpoint to OpenAPI spec (#195)

Author: ksinder

CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance for Claude Code when working with this repository.
+
+## Project Overview
+
+This is the Notion MCP Server - an [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes the [Notion API](https://developers.notion.com/reference/intro) as MCP tools. It auto-generates tools from an OpenAPI specification.
+
+## Architecture
+
+```
+scripts/notion-openapi.json    # OpenAPI spec (source of truth for all tools)
+        ↓
+src/init-server.ts             # Loads & validates spec, creates MCPProxy
+        ↓
+src/openapi-mcp-server/
+├── openapi/parser.ts          # Converts OpenAPI → MCP tools
+├── mcp/proxy.ts               # Registers tools with MCP server
+└── client/http-client.ts      # Executes API calls
+```
+
+## Key Patterns
+
+### Adding New Endpoints
+
+Only modify `scripts/notion-openapi.json`. Tools are auto-generated from the spec - no code changes needed elsewhere.
+
+### Tool Generation Flow
+
+1. `OpenAPIToMCPConverter.convertToMCPTools()` iterates all paths/operations
+2. Each operation becomes an MCP tool (name = `operationId`)
+3. Parameters + requestBody → `inputSchema`
+4. Response schema → `returnSchema`
+5. `MCPProxy.setupHandlers()` registers tools with the MCP SDK
+
+### Naming Conventions
+
+- Tool names come from OpenAPI `operationId` (e.g., `retrieve-a-database`)
+- Names are truncated to 64 chars and converted to title case for display
+
+## Common Commands
+
+```bash
+npm run build      # TypeScript compilation + CLI bundling
+npm test           # Run vitest tests
+npm run dev        # Start dev server with hot reload
+```
+
+## File Structure
+
+- `scripts/notion-openapi.json` - OpenAPI 3.1.0 spec defining all Notion API endpoints
+- `scripts/start-server.ts` - Entry point
+- `src/init-server.ts` - Server initialization
+- `src/openapi-mcp-server/` - Core MCP server implementation
+  - `openapi/parser.ts` - OpenAPI to MCP conversion (529 lines)
+  - `mcp/proxy.ts` - MCP tool registration and execution (209 lines)
+  - `client/http-client.ts` - HTTP request execution (198 lines)
+
+## Testing
+
+Tests are in `__tests__` directories adjacent to source files. Run with `npm test`.
+
+## API Version
+
+Uses Notion API version `2025-09-03` (Data Source Edition). The spec includes both:
+- `/v1/databases/{database_id}` - Traditional database endpoints
+- `/v1/data_sources/{data_source_id}` - New data source endpoints

README.md

@@ -29,21 +29,21 @@ This project implements an [MCP server](https://spec.modelcontextprotocol.io/) f
 
 ### What changed
 
-**Removed tools (4):**
+**Removed tools (3):**
 
 - `post-database-query` - replaced by `query-data-source`
-- `retrieve-a-database` - replaced by `retrieve-a-data-source`
 - `update-a-database` - replaced by `update-a-data-source`
 - `create-a-database` - replaced by `create-a-data-source`
 
-**New tools (6):**
+**New tools (7):**
 
 - `query-data-source` - Query a data source (database) with filters and sorts
 - `retrieve-a-data-source` - Get metadata and schema for a data source
 - `update-a-data-source` - Update data source properties
 - `create-a-data-source` - Create a new data source
 - `list-data-source-templates` - List available templates in a data source
 - `move-page` - Move a page to a different parent location
+- `retrieve-a-database` - Get database metadata including its data source IDs
 
 **Parameter changes:**
 
@@ -60,11 +60,12 @@ If you have hardcoded tool names or prompts that reference the old database tool
 | Old Tool (v1.x) | New Tool (v2.0) | Parameter Change |
 | -------------- | --------------- | ---------------- |
 | `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |
-| `retrieve-a-database` | `retrieve-a-data-source` | `database_id` → `data_source_id` |
 | `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |
 | `create-a-database` | `create-a-data-source` | No change (uses `parent.page_id`) |
 
-**Total tools now: 21** (was 19 in v1.x)
+> **Note:** `retrieve-a-database` is still available and returns database metadata including the list of data source IDs. Use `retrieve-a-data-source` to get the schema and properties of a specific data source.
+
+**Total tools now: 22** (was 19 in v1.x)
 
 ---
 

package-lock.json

@@ -6,7 +6,7 @@
     "mcp",
     "server"
   ],
-  "version": "2.0.0",
+  "version": "2.1.0",
   "license": "MIT",
   "type": "module",
   "scripts": {

package.json

@@ -268,6 +268,10 @@
     }
   ],
   "tags": [
+    {
+      "name": "Databases",
+      "description": "Database endpoints for retrieving database metadata"
+    },
     {
       "name": "Data sources",
       "description": "Data source endpoints for querying and managing databases"
@@ -2063,6 +2067,70 @@
         "security": []
       }
     },
+    "/v1/databases/{database_id}": {
+      "get": {
+        "summary": "Retrieve a database",
+        "description": "Retrieves a database object using the ID specified. Returns database metadata including the list of data source IDs contained in the database.",
+        "operationId": "retrieve-a-database",
+        "tags": [
+          "Databases"
+        ],
+        "parameters": [
+          {
+            "name": "database_id",
+            "in": "path",
+            "description": "Identifier for a Notion database",
+            "schema": {
+              "type": "string"
+            },
+            "required": true
+          },
+          {
+            "$ref": "#/components/parameters/notionVersion"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "object": {
+                      "type": "string",
+                      "example": "error"
+                    },
+                    "status": {
+                      "type": "integer",
+                      "example": 400
+                    },
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "deprecated": false,
+        "security": []
+      }
+    },
     "/v1/pages/{page_id}/move": {
       "post": {
         "summary": "Move a page",