@use-tusk/unit-tests-onboarding-mcp

MCP server for Tusk unit tests onboarding. Runs inside E2B sandbox and communicates with Tusk backend API to verify sandbox configurations.

How It's Used

This MCP is pre-installed in the E2B template (unit-test-onboarding-sandbox). When the sandbox starts, E2BOnboardingProvider adds it to Claude Code with the appropriate environment variables.

┌─────────────────────────────────────────────────────────────────┐
│  E2B Sandbox (unit-test-onboarding-sandbox template)            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Claude Code                                            │    │
│  │  - Writes .tusk/ files                                  │    │
│  │  - Calls MCP tools via stdio                            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                       │ stdio                                   │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  unit-tests-onboarding-mcp (local process)              │    │
│  │  - Reads .tusk/ files from filesystem                   │    │
│  │  - POSTs to Tusk API via HTTPS                          │    │
│  │  - Polls for results                                    │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                        │ HTTPS
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  Tusk Backend API (/onboarding/*)                               │
└─────────────────────────────────────────────────────────────────┘

The agent (Claude Code) calls these tools to:

1. verifySandboxConfig - Verify sandbox configs work (runs setup, tests, lint, coverage)
2. askUserForInput - Ask the user questions
3. askUserForEnvVars - Request environment variables from the user
4. finishConfig - Save the config and complete onboarding
5. unableToCreateConfig - Report that a config couldn't be created

Environment Variables

Set by E2BOnboardingProvider when adding the MCP:

| Variable | Description | | -------------------- | --------------------------------------------------------- | | TUSK_API_URL | Tusk backend API URL (e.g., https://api.usetusk.ai/api) | | TUSK_SESSION_TOKEN | Session token for authentication | | TUSK_CONFIG_RUN_ID | Config run ID (for logging) |

Tools

verifySandboxConfig

Verify that the sandbox config works by running setup, tests, lint, and coverage.

Parameters:

• configPath (string, required): Absolute path to .tusk/ directory

Returns: Verification results with detailed logs for any failed steps.

askUserForInput

Ask the user a question and wait for their response.

Parameters:

• question (string, required): The question to ask
• options (string[], optional): Multiple choice options

Returns: The user's answer.

askUserForEnvVars

Request environment variables from the user.

Parameters:

• envVars (array, required): List of env vars to request
  • key (string): Variable name (e.g., "DATABASE_URL")
  • isSecret (boolean): Whether the value should be masked
  • description (string): Why this variable is needed

Returns: The provided environment variable values.

finishConfig

Save the sandbox configuration and complete onboarding.

Parameters:

• scriptStatuses (object, required):
  • setupScript: "working" | "not-working"
  • testScript: "working" | "not-working"
  • lintScript: "working" | "not-needed" | "not-working" (optional)
  • coverageScript: "working" | "not-supported" | "partial-working" | "not-working" (optional)
• notes (string, optional): Additional notes
• attemptedButFailed (array, optional): Steps that were tried but couldn't be made to work

Returns: Success confirmation.

unableToCreateConfig

Report that you were unable to create a working config.

Parameters:

• reason (string, required): High-level explanation
• blockers (array, required): Specific blockers encountered
  • type: One of: missing_dependency, unsupported_framework, unsupported_language, needs_vpn, needs_secrets, needs_external_service, docker_not_supported, ci_config_complex, tests_flaky, other
  • description: Description of the blocker
• verificationAttempts (array, optional): Previous verification attempts

Returns: Confirmation message.

Publishing & Releases

Important: This package is pre-installed in the E2B template.

cd packages/unit-tests-onboarding-mcp
npm run release patch  # or minor/major

This bumps the version and publishes to npm. After publishing:

1. Update version in backend/src/e2b_templates/unit-test-onboarding-sandbox/build.ts
2. Rebuild template: cd backend && npm run e2b:build -- src/e2b_templates/unit-test-onboarding-sandbox/build.ts

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Run in development mode
TUSK_API_URL=http://localhost:8000/api \
TUSK_SESSION_TOKEN=test-token \
npm run dev

# Test with MCP inspector
TUSK_API_URL=http://localhost:8000/api \
TUSK_SESSION_TOKEN=test-token \
npm run inspector

Type Sync

Types in src/types.ts are mirrored from backend. See file for source locations. When updating types, update both files and add SYNC comments.

Backend files that should stay in sync:

• backend/src/services/onboarding/unit-tests/providers/OnboardingSandboxProvider.ts
• backend/src/models/onboarding/UnitTestsConfigVerificationRun.ts
• backend/src/types/onboarding/completionResult.ts
• backend/src/api/onboarding/schemas/mcpApiSchemas.ts
• backend/src/services/onboarding/unit-tests/types/verificationTypes.ts

TODOs

• [ ] Add tests for the MCP server
• [ ] Add lint/formatting to the MCP server
• [ ] Create CI workflow for MCP server