Harden the vendored OpenAPI->MCP fork (#317)

The src/openapi-mcp-server/ tree is a vendored fork of snaggle-ai/
openapi-mcp-server v1 (MIT; upstream went an incompatible direction in v2,
so there's no upgrade path). This makes ownership of it deliberate and safe
rather than incidental:

- License compliance: add the upstream MIT LICENSE/copyright (Jan Wilmake)
  in the vendored dir, as the MIT terms require. It was previously dropped.
- Regression guard: snapshot the MCP tool surface generated from the real
  scripts/notion-openapi.json (names, HTTP method, descriptions, params), so
  any future change to the converter — or a swap to a different engine — is
  caught with a reviewable diff.
- Dead code: remove the unused convertToOpenAITools / convertToAnthropicTools
  converters (and the now-orphaned convertOperationToJsonSchema helper and
  FunctionParameters type). This drops the only uses of the `openai` and
  `@anthropic-ai/sdk` devDependencies, which are removed.
- Document why it's forked and how to change it safely.

No runtime behavior change. Build + full test suite pass (83 tests).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ksinder

package-lock.json

@@ -34,7 +34,6 @@
     "zod": "3.24.1"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.33.1",
     "@types/express": "^5.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/json-schema": "^7.0.15",
@@ -44,7 +43,6 @@
     "@vitest/coverage-v8": "^4.0.18",
     "esbuild": "^0.25.2",
     "multer": "1.4.5-lts.1",
-    "openai": "^4.91.1",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vitest": "^4.0.18"

package.json

@@ -0,0 +1,29 @@
+The code in this directory is a vendored fork of v1 of
+https://github.com/snaggle-ai/openapi-mcp-server, used under the MIT License.
+Its original license and copyright notice are reproduced below, as required by
+the MIT License. Modifications made by Notion Labs, Inc. are likewise released
+under the MIT License (see the LICENSE file at the repository root).
+
+----------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2025 Jan Wilmake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/openapi-mcp-server/LICENSE

@@ -1,3 +1,35 @@
-Note: This is a fork from v1 of https://github.com/snaggle-ai/openapi-mcp-server. The library took a different direction with v2 which is not compatible with our development approach.
+# openapi-mcp-server (vendored)
 
-Forked to upgrade vulnerable dependencies and easier setup.
+This directory converts Notion's OpenAPI spec into MCP tools and executes the
+underlying API calls. It is a **vendored fork** of v1 of
+[`snaggle-ai/openapi-mcp-server`](https://github.com/snaggle-ai/openapi-mcp-server)
+(MIT). See [`LICENSE`](./LICENSE) for the upstream copyright notice.
+
+## Why it's vendored (and why we keep it)
+
+Upstream took a different direction in v2 — it became an API *discovery*
+meta-tool and is no longer a one-tool-per-endpoint converter — so there is no
+upgrade path. We own this code deliberately. It is small, has no external
+runtime dependencies of its own beyond what the server already ships, and
+encodes **Notion-specific behavior** that off-the-shelf OpenAPI→MCP libraries do
+not reproduce:
+
+- `"Notion | "` prefix on tool descriptions (`parser.ts`, `getDescription`).
+- Tolerance for clients that double-serialize nested JSON params: complex
+  schemas are widened to `anyOf: [schema, string]` (`parser.ts`,
+  `withStringFallback`) and decoded at call time (`proxy.ts`, `deserializeParams`).
+  See issues [#176](https://github.com/makenotion/notion-mcp-server/issues/176)
+  and [#208](https://github.com/makenotion/notion-mcp-server/issues/208).
+- `readOnly` / `destructive` tool annotations derived from the HTTP method
+  (`proxy.ts`).
+- Multipart/file-upload operations mapped to local-file-path string params
+  (`parser.ts` binary handling, `file-upload.ts`).
+- 64-char tool-name truncation with a uniqueness suffix (`parser.ts`,
+  `ensureUniqueName`).
+
+## Changing it safely
+
+`openapi/__tests__/notion-spec.snapshot.test.ts` snapshots the tools generated
+from the real `scripts/notion-openapi.json` spec (names, descriptions, parameter
+surface). If a change alters the public tool surface, that snapshot will fail —
+review the diff and update with `vitest -u` only if the change is intentional.