Harden the vendored OpenAPI→MCP fork (license, snapshot test, dead code)#317
Merged
Conversation
vshen-notion
approved these changes
Jun 17, 2026
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>
ksinder
force-pushed
the
ksinder-harden-openapi-fork
branch
from
689c2ac to
5f7fca4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
src/openapi-mcp-server/is a vendored fork ofsnaggle-ai/openapi-mcp-serverv1 (MIT). Upstream rewrote v2 into an incompatible API-discovery meta-tool, so there's no upgrade path — we own this code. This PR makes that ownership deliberate and safe instead of incidental (no runtime behavior change).After researching maintained OpenAPI→MCP libraries (
@ivotoby/openapi-mcp-server,openapi-mcp-generator, snaggle v2, the MCP SDK), the conclusion was that none is a clean drop-in: each would force us to re-implement our Notion-specific behavior (the"Notion | "description prefix, double-serialized-param tolerance for #176/#208, read-only/destructive annotations, multipart file uploads, 64-char name truncation) and take on a single-maintainer runtime dependency in the official server. So we keep the converter — and harden it.What changed
LICENSE(Copyright © 2025 Jan Wilmake) inside the vendored dir. MIT requires the original notice be retained; it had been dropped (only Notion's root LICENSE was present).notion-spec.snapshot.test.tssnapshots the MCP tool surface generated from the realscripts/notion-openapi.json(tool names, HTTP method, descriptions, parameter surface; 22 tools). Any change to the converter — or a future engine swap — now produces a reviewable diff instead of silently shifting the public tool surface.convertToOpenAITools/convertToAnthropicTools(and the now-orphanedconvertOperationToJsonSchemahelper +FunctionParameterstype). These were the only consumers of theopenaiand@anthropic-ai/sdkdevDependencies, which are removed.src/openapi-mcp-server/README.mdnow explains why it's forked, what Notion-specific behavior it encodes, and how to change it safely.How was this change tested?
npm run buildpasses; build artifacts remain gitignored so CI's "no uncommitted changes" check is unaffected.🤖 Generated with Claude Code