Vendor and wire up the community QuickBase MCP server so Sasha operators can create, query, and maintain QuickBase apps without leaving Studio.
Follow the existing MCP integration pattern (vendored server + wrapper + smoke tests + Claude CLI registration) and the setup guidance in deployed-md-files/docs/tools/mcp-setup-advice.md to keep registrations reliable.
Ship first-class operator docs (Settings ➝ Tools) and user-facing tool discovery content so the integration surfaces automatically in the Tools panel.
Upstream Server Packaging (integrations/mcp/quickbase/)
Record the upstream commit hash in UPSTREAM_COMMIT; keep docs/LESSONS-LEARNED.md style notes for deviations if patches are required.
Dependencies & builds
Reproduce upstream package.json/package-lock.json; add npm run build output (dist/) to the vendored tree so the runtime never needs to compile.
Provide run-quickbase-mcp.js wrapper (ESM, #!/usr/bin/env node, chmod +x) that imports the built entry point (dist/index.js). Wrapper should validate QB_REALM, QB_USER_TOKEN, and QB_APP_ID, logging issues to stderr only per the MCP setup doc.
Include a smoke-test.js harness (mirroring Postmark/Companies House) that uses @modelcontextprotocol/sdk to issue a safe tool call such as quickbase_test_connection with configurable fake creds.
Runtime assets
Ensure npm install, npm run build, and npm prune --omit=dev run inside the Docker build so node_modules/ is ready in deployments.
Add a concise README summarizing supported tools (application, table, field, record, relationship, utilities) and pointing to configuration docs inside Sasha.
Credential Persistence & Service Layer
Service moduleclaudecodeui/server/services/quickbaseMcpService.js
Model after companiesHouseMcpService.js with helpers to loadConfig, saveConfig, registerServer, removeServer, runSmokeTest, and getStatus.
Use the shared encryption utility for the user token. When returning config to the UI, expose only booleans like hasUserToken.
Registration workflow
Invoke claude mcp add -s user quickbase --env QB_REALM=... --env QB_USER_TOKEN=... --env QB_APP_ID=... -- run-quickbase-mcp.js, matching the claude mcp add best practices from deployed-md-files/docs/tools/mcp-setup-advice.md (wrapper script, env args before --, paths resolved with path.resolve).
Remove existing registrations gracefully before re-adding. Capture stdout/stderr for operator logs.
Smoke testing
Provide a runSmokeTest that spawns node smoke-test.js with sanitized env vars; persist timestamp + snippet of results back into the config file.
Tool status plumb
Extend toolStatusService.js to include Quickbase readiness (Configured ➝ Registered ➝ Healthy) so the UI dashboard stays consistent.
API Routes & Secret Management
Routerclaudecodeui/server/routes/mcp-quickbase.js
REST surface (GET /status, POST /configure, POST /register, DELETE /register, POST /test).
Input validation enforcing required fields: realm (host only), appId, userToken. Optional defaults should be strings with len <= 255; timeoutMs limited to < 120000, maxRetries < 10.
configure writes encrypted token; status redacts it; register triggers CLI add; test runs smoke test.
Routing glue
Mount router under /api/mcp/quickbase in server/routes/mcp.js.
Update any central integration registries (e.g., server/services/toolStatusService.js, server/routes/mcp/index.js) to include Quickbase metadata.
Secret storage
Reuse the existing secretStore abstraction when persisting tokens; confirm values also land in /home/sasha/config/mcp/ for non-container setups.
Add Quickbase integration state (form fields + status). Fields: Realm (host portion only), App ID, User token, optional table/report defaults, MCP timeout/retry settings, toggle for enabling experimental bulk operations.
Buttons: Save, Register, Remove, Run Test; last run/test results panel.
Inline helper text explaining how to create Quickbase user tokens (steps from upstream README).
Disable register/test buttons until creds saved; show badges for Configured, Registered, Healthy.
Integration summaries
Extend integrationSummaries/integrationCards with Quickbase entry (friendly label “Quickbase Workspace Automation”).
Update ChatInterface tool prefix map so Quickbase tools show up (e.g., Quickbase: prefix) when registered.
Error surfacing
Present stderr/stdout from register/test commands similar to other integrations with monospace log blocks and positive “success” logs to avoid docbuilder-style ambiguity.
Follow /docs/tools/tool-documentation-template.md: describe capabilities, common business tasks (new project tracking tables, bulk updates, relationship maintenance, reporting), example prompts leveraging provided tools, and link back to Settings ➝ Tools for setup.
Use a business-friendly title—avoid “MCP” in the heading so it appears cleanly in the Tools panel per the deployed instructions.
README updates
Mention Quickbase under integrations list in README.md or relevant docs/sasha sections so stakeholders discover it.
Testing & Verification
Local runtime
npm install && npm run build inside integrations/mcp/quickbase/; run node run-quickbase-mcp.js --help (should exit 0 when env missing with clear message).
Execute node smoke-test.js with mock env to ensure MCP handshake works and logging stays on stderr for noise per mcp-setup-advice.md.
Application flow
Save creds via UI ➝ expect encrypted persistence.
Register server, confirm claude mcp list shows quickbase.
Hit Tools panel to verify Quickbase doc renders and tools show up (maybe using the sample prompts).
Integration tests
Add optional Playwright/API test (if feasible) that uses mock Quickbase responses (via upstream server’s test harness) to validate error paths (invalid token, missing table).
For Docker builds, ensure integration dir copied + wrapper executable bit preserved; run smoke test inside container as part of CI script.
Security, Logging & Observability
Store the Quickbase user token encrypted at rest; never echo it in logs or UI responses.
Add rate-limit/backoff knobs (timeout, retries) to the config so operators can tune behavior for large tables.
Surface success/failure logs with actionable messages (realm/app mismatch, invalid table IDs) while masking sensitive IDs when possible.
Consider optional health check endpoint that pings quickbase_test_connection nightly and records status for on-call dashboards.
Risks & Open Questions
Quickbase API quotas – need clarity on rate limits per user token; plan for exponential backoff and operator-configurable throttles.
Schema drift – Quickbase tables are highly customized; confirm upstream server gracefully handles missing fields/relationships. Might require additional validation or UI hints.
Credential scope – confirm whether per-app tokens are acceptable or if multiple app IDs must be supported (potential future enhancement: support multiple app profiles).
Testing data – identify a staging Quickbase realm we can safely hit for automated smoke tests; else, mock responses.
Version drift – upstream project is community-run; decide on cadence for UPSTREAM_COMMIT updates and add a checklist (build, test, docs) when re-vendoring.