Add Appa MCP Enhancer integration

[zthewriter]

Summary

• Adds integrations/appa-mcp-enhancer — a full GitBook integration that enhances docs MCP with additional context sources (GitHub repos, websites, other MCP endpoints) through Appa's no-code MCP Studio.
• Adds a guide doc for the MCP enhancer architecture pattern.

What's included

Integration code (integrations/appa-mcp-enhancer/)

• gitbook-manifest.yaml — manifest with account-level connect flow, space-level config (endpoint URL, auto-sync toggle), and scopes
• src/index.tsx — createIntegration() entry point with:
  • /connect route that redirects to Appa for account linking
  • /callback route that provisions an MCP server via Appa API and stores credentials
  • /status JSON endpoint for health checks
  • /webhook route for external content update triggers
  • space_content_updated event handler for automatic re-indexing
  • ContentKit status block showing connection state, sources, and call count
• src/appa.ts — Appa API client (provision, sync, status)
• src/types.ts — typed configuration interfaces
• package.json / tsconfig.json — standard integration package setup

Guide doc (docs/integrations/guides/)

• Architecture pattern for MCP enhancer integrations
• Security, reliability, and publishing checklists

How it works

1. User installs the integration in a GitBook space
2. Clicks "Connect Appa" → redirects to Appa sign-in
3. On callback, Appa provisions an MCP server with the GitBook space as the first source
4. User adds more sources (repos, websites, MCP URLs) in MCP Studio
5. One combined MCP endpoint is returned for use in Cursor, Claude Desktop, etc.
6. Content updates in GitBook trigger automatic re-indexing

Test plan

• Verify manifest validates with gitbook check
• Verify TypeScript compiles with tsc --noEmit
• Test connect → callback → provision flow end-to-end
• Test auto-sync on space_content_updated event
• Verify status block renders in GitBook editor

[changeset-bot]

🦋 Changeset detected

Latest commit: 29eb473

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@gitbook/integration-appa-mcp-enhancer	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

bun add https://pkg.pr.new/GitbookIO/integrations/@gitbook/api@1172

commit: 29eb473

[zthewriter]

Quick maintainer-facing update after production validation + CI triage:

What I pushed to this PR branch

• Added a changeset for @gitbook/integration-appa-mcp-enhancer
• Regenerated bun.lock with Bun 1.3.3 to satisfy bun install --frozen-lockfile

Why checks were failing

1. bun install --frozen-lockfile failures in Test/Format/Typecheck/Build/Publish prereleases:

   • CI logs show: lockfile had changes, but lockfile is frozen
   • This should be addressed by the lockfile update now on this branch.

2. Check integrations failure is environment/secret related:

   • OP_SERVICE_ACCOUNT_TOKEN is empty in PR context, so 1Password setup fails (No accounts configured for use with 1Password CLI).
   • Recommendation for maintainers: gate this job (or just the 1Password-dependent step) when the secret is unavailable in external PR contexts.

Functional notes from MCP Studio backend validation

• Provisioning and MCP endpoint contracts used by this integration are live and working in production.
• Upgrade/error paths are enforced and stable:
  • source-slot overage returns 402 source_limit_reached + purchase URL
  • call-limit overage returns JSON-RPC -32000 with pricing guidance

Happy to iterate further if maintainers want stricter CI behavior on external PRs.