@typelets/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Typelets
+
+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.

package/README.md

@@ -0,0 +1,148 @@
+# typelets-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server for [Typelets](https://typelets.com), the collaborative IDE for technical interviews and pair programming. Connect an MCP-capable client (Claude Desktop, Cline, Cursor, Codex, etc.) and let it list workspaces, browse the problem library, read candidate files, summarize sessions, and (later) write back to the workspace on your behalf.
+
+Status: pre-alpha. The spec below is the plan; the server is being built in public.
+
+## Why
+
+Interviewers spend a lot of meta-work outside the coding window: authoring problems, prepping starter files, reviewing candidate code after the fact, summarizing what happened. Most of that work is "look at structured data, produce structured data," which is exactly what an LLM is good at. Wrapping the Typelets API as MCP tools lets the interviewer's AI of choice do that work without the platform itself needing to embed model logic.
+
+## Phased plan
+
+| Phase | Scope | Risk |
+| --- | --- | --- |
+| 1 | Read-only: list workspaces, list problems, get problem detail, read workspace tree + file contents, fetch recording metadata, list pending invites | Low. Nothing the LLM does here can change platform state. |
+| 2 | Authoring: create workspace, apply problem to workspace, draft/edit a library problem, materialize starter files | Medium. Writes happen, but always against the caller's own resources. |
+| 3 | Session intelligence: summarize a recording transcript, draft scores against the rubric, suggest follow-up questions, batch-import problems from a corpus | Higher. Outputs land on candidate-facing records, so there is a review gate before they take effect. |
+
+Phase 1 is the entire v0.1.0 release. Phase 2 lands in v0.2.x. Phase 3 is v0.3.x once we have a UX answer for "review before commit".
+
+## How auth works
+
+The server authenticates against the Typelets API using a **Personal Access Token**. Tokens are issued in User Settings -> Tokens on https://typelets.com, are scoped per-user, and carry an expiry plus a label. Tokens never leave the user's machine. The MCP server reads `TYPELETS_TOKEN` from its environment, and the client passes it through.
+
+Why not OAuth: this is a single-user CLI tool wired into a desktop LLM client. PATs match the audience without dragging in a browser dance every session. An OAuth flow becomes plausible later if a Typelets-hosted MCP gateway makes sense.
+
+Why not session cookies: cookies are scoped to a browser and expire on the platform's schedule, not the user's. A PAT is the right primitive for "a programmable agent acting as me."
+
+The PAT issuance flow is the only prerequisite work on the Typelets side. Everything else in this repo just wraps existing endpoints.
+
+## Two profiles
+
+The server ships two profiles:
+
+- **`interviewer`** (default): has access to rubric content, hidden tests, scores, and the full library.
+- **`candidate`** (strict): hides rubric / hidden tests / scores even if the user's role would otherwise allow it. Useful when the user wants to point an AI assistant at their own in-progress interview without leaking the answer key into the LLM's context.
+
+The profile is set at start-up, not per-tool:
+
+```bash
+TYPELETS_PROFILE=candidate npx @typelets/mcp
+```
+
+Default is `interviewer`. The server refuses to switch profiles at runtime. If you want both, run two server instances on different ports.
+
+## Install
+
+```bash
+npx @typelets/mcp
+```
+
+In your MCP client's config (Claude Desktop, Cline, Cursor, etc.):
+
+```jsonc
+{
+  "mcpServers": {
+    "typelets": {
+      "command": "npx",
+      "args": ["@typelets/mcp"],
+      "env": {
+        "TYPELETS_TOKEN": "pat_…",
+        "TYPELETS_API_URL": "https://api.typelets.com",
+        "TYPELETS_PROFILE": "interviewer"
+      }
+    }
+  }
+}
+```
+
+Get your token at https://typelets.com: User Settings → Tokens → New token. Give it a label like "Claude Desktop on laptop", pick an expiry, copy the value (you only see it once), and paste it into `TYPELETS_TOKEN`.
+
+Profiles:
+- `interviewer` (default): full surface, including rubric and hidden tests.
+- `candidate`: the same tools but rubric, criteria, hidden tests, and solution are stripped before they reach the LLM. Use this when you want an AI assistant helping you on a problem you're solving.
+
+## Tool surface
+
+16 tools total. In `candidate` profile, the 5 interviewer-only tools are not registered; the candidate's host LLM does not see them in `listTools`.
+
+### Reads (8 tools, both profiles)
+
+| Tool | Reads | Notes |
+| --- | --- | --- |
+| `list_workspaces` | `GET /workspaces` | Caller's workspaces, with role + mode. |
+| `get_workspace` | `GET /workspaces/:id` | Full summary, share scope, applied problem id. |
+| `list_workspace_files` | `GET /workspaces/:id/files` | Flat list of file ids + slash-separated paths. |
+| `read_workspace_file` | `GET /workspaces/:id/files/:fileId/content` | UTF-8 content at HEAD; 1 MiB cap with `truncated` flag. |
+| `list_problems` | `GET /problems` | Library entries the caller can see. |
+| `get_problem` | `GET /problems/:id` | Prompt + criteria. Rubric / hidden tests stripped in candidate profile. |
+| `list_recordings` | `GET /workspaces/:id/recordings` | Metadata only. |
+| `list_pending_invites` | `GET /invites` + `GET /invitations` | Merged workspace + org invites. |
+
+### Writes: file CRUD (3 tools, both profiles)
+
+| Tool | Writes | `destructive` |
+| --- | --- | --- |
+| `create_file` | `POST /workspaces/:id/files` | |
+| `update_file` | `PUT /workspaces/:id/files/:fileId/content` | ✓ |
+| `delete_file` | `DELETE /workspaces/:id/files/:fileId` | ✓ |
+
+### Writes: authoring (5 tools, interviewer profile only)
+
+| Tool | Writes | `destructive` |
+| --- | --- | --- |
+| `create_workspace` | `POST /workspaces` | |
+| `apply_problem_to_workspace` | `POST /workspaces/:id/interview/problem` | ✓ |
+| `save_problem_to_library` | `POST /problems` | |
+| `edit_problem` | `PATCH /problems/:id` | ✓ |
+| `delete_problem` | `DELETE /problems/:id` | ✓ |
+
+Tools marked `destructive` carry the MCP `destructiveHint: true` annotation so host clients (Claude Desktop, Cline, Cursor) prompt the user before invocation.
+
+## Layout
+
+```
+typelets-mcp/
+├─ README.md                  (this file)
+├─ LICENSE
+├─ package.json
+├─ tsconfig.json
+├─ .gitignore
+├─ .github/
+│  └─ workflows/
+│     └─ ci.yml               (typecheck + lint + test on push)
+├─ src/
+│  ├─ index.ts                (server entry; wires stdio transport + handlers)
+│  ├─ env.ts                  (parses TYPELETS_TOKEN / API_URL / PROFILE)
+│  ├─ client.ts               (thin fetch wrapper around the Typelets API)
+│  ├─ profile.ts              (interviewer vs candidate gating)
+│  └─ tools/
+│     ├─ list_workspaces.ts
+│     ├─ get_workspace.ts
+│     ├─ list_workspace_files.ts
+│     ├─ read_workspace_file.ts
+│     ├─ list_problems.ts
+│     ├─ get_problem.ts
+│     ├─ list_recordings.ts
+│     └─ list_pending_invites.ts
+└─ tests/                     (unit tests + recorded API fixtures)
+```
+
+## Contributing
+
+Once v0.1.0 ships and the PAT flow is live on https://typelets.com, the repo will be open to issues + PRs. For now, watch the milestones tab.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Thin fetch wrapper around the Typelets API. Adds the Authorization
+ * header, JSON content-type, and a uniform error shape so individual
+ * tool handlers don't have to repeat the same plumbing.
+ *
+ * The server intentionally does NOT cache responses. Each tool call is
+ * a fresh request so the LLM never sees stale data, and the user keeps
+ * a real-time view of platform state from inside the chat.
+ */
+import type { Env } from './env.js';
+export declare class TypeletsApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined);
+}
+export interface TypeletsClient {
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+export declare function createClient(env: Env): TypeletsClient;

package/dist/client.js

@@ -0,0 +1,58 @@
+export class TypeletsApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'TypeletsApiError';
+    }
+}
+export function createClient(env) {
+    async function request(method, path, body) {
+        const url = `${env.apiUrl}${path}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `Bearer ${env.token}`,
+        };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        // exactOptionalPropertyTypes refuses an explicit `undefined`; build
+        // the init object incrementally so `body` is only present when we
+        // actually have one.
+        const init = { method, headers };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const res = await fetch(url, init);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        let json = null;
+        if (text.length > 0) {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                // Non-JSON response body (HTML error page, plain text). Leave
+                // json as null so the caller can decide whether to keep going
+                // or fail; the raw text rides along on the error for debugging.
+                json = text;
+            }
+        }
+        if (!res.ok) {
+            const message = (json !== null && typeof json === 'object' && 'error' in json && typeof json.error === 'string')
+                ? json.error
+                : `Typelets API ${method} ${path} failed with ${res.status}`;
+            throw new TypeletsApiError(res.status, message, json);
+        }
+        return json;
+    }
+    return {
+        get: (path) => request('GET', path),
+        post: (path, body) => request('POST', path, body),
+        put: (path, body) => request('PUT', path, body),
+        patch: (path, body) => request('PATCH', path, body),
+        delete: (path) => request('DELETE', path),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAEvB;IAEA;IAHlB,YACkB,MAAc,EAC9B,OAAe,EACC,IAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAU;QAG9B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAUD,MAAM,UAAU,YAAY,CAAC,GAAQ;IACnC,KAAK,UAAU,OAAO,CACpB,MAAmD,EACnD,IAAY,EACZ,IAAc;QAEd,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QACnC,MAAM,OAAO,GAA2B;YACtC,MAAM,EAAE,kBAAkB;YAC1B,aAAa,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE;SACrC,CAAC;QACF,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAErE,oEAAoE;QACpE,kEAAkE;QAClE,qBAAqB;QACrB,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC9C,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAEnC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAc,CAAC;QAE9C,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,IAAI,GAAY,IAAI,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC;gBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YAAC,MAAM,CAAC;gBACP,8DAA8D;gBAC9D,8DAA8D;gBAC9D,gEAAgE;gBAChE,IAAI,GAAG,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,OAAO,GACX,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC;gBAC9F,CAAC,CAAC,IAAI,CAAC,KAAK;gBACZ,CAAC,CAAC,gBAAgB,MAAM,IAAI,IAAI,gBAAgB,GAAG,CAAC,MAAM,EAAE,CAAC;YACjE,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,IAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;QACnC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;QACjD,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC;QAC/C,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC;QACnD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,6 @@
+export interface Env {
+    token: string;
+    apiUrl: string;
+    profile: 'interviewer' | 'candidate';
+}
+export declare function readEnv(): Env;

package/dist/env.js

@@ -0,0 +1,36 @@
+/**
+ * Configuration the server reads from its process environment at start-up.
+ * The MCP server is invoked by a client (Claude Desktop, Cline, etc.) which
+ * supplies these via the client's mcpServers config, not by the user
+ * directly, so a missing or malformed value should surface as a clear
+ * stderr message before any tool registration happens.
+ */
+import { z } from 'zod';
+/**
+ * Personal Access Token issued at typelets.com/settings/tokens. Required.
+ * Stored on disk only in the host client's MCP config; never leaves the
+ * caller's machine.
+ */
+const tokenSchema = z.string().min(20, 'TYPELETS_TOKEN looks too short to be a real PAT.');
+/**
+ * API base URL. Defaults to production. Local development against a
+ * self-hosted Typelets instance overrides this.
+ */
+const apiUrlSchema = z
+    .string()
+    .url()
+    .default('https://api.typelets.com');
+/**
+ * Which tool surface to expose. `interviewer` (default) sees rubric +
+ * hidden test content. `candidate` strips it out so an AI assistant
+ * helping a candidate can not be fed the answer key. The profile is
+ * fixed at start-up; the server refuses to switch it at runtime.
+ */
+const profileSchema = z.enum(['interviewer', 'candidate']).default('interviewer');
+export function readEnv() {
+    const token = tokenSchema.parse(process.env.TYPELETS_TOKEN);
+    const apiUrl = apiUrlSchema.parse(process.env.TYPELETS_API_URL);
+    const profile = profileSchema.parse(process.env.TYPELETS_PROFILE);
+    return { token, apiUrl, profile };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,kDAAkD,CAAC,CAAC;AAE3F;;;GAGG;AACH,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,EAAE;KACR,GAAG,EAAE;KACL,OAAO,CAAC,0BAA0B,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAQlF,MAAM,UAAU,OAAO;IACrB,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the Typelets MCP server.
+ *
+ * Runs over stdio (the transport every desktop MCP client speaks today).
+ * On start-up we:
+ *   1. Read + validate the env (token, api url, profile).
+ *   2. Build a thin API client.
+ *   3. Register the Phase 1 read tools and the Phase 2 write tools.
+ *   4. Hand off to the MCP SDK's stdio transport loop.
+ *
+ * Phase 2 write tools are profile-gated at registration time.
+ * interviewer-only tools are not registered when TYPELETS_PROFILE=candidate.
+ * Phase 3 (session intelligence) lands in a later minor release.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readEnv } from './env.js';
+import { createClient } from './client.js';
+import { registerListWorkspaces } from './tools/list_workspaces.js';
+import { registerGetWorkspace } from './tools/get_workspace.js';
+import { registerListWorkspaceFiles } from './tools/list_workspace_files.js';
+import { registerReadWorkspaceFile } from './tools/read_workspace_file.js';
+import { registerListProblems } from './tools/list_problems.js';
+import { registerGetProblem } from './tools/get_problem.js';
+import { registerListRecordings } from './tools/list_recordings.js';
+import { registerListPendingInvites } from './tools/list_pending_invites.js';
+import { registerCreateFile } from './tools/create_file.js';
+import { registerUpdateFile } from './tools/update_file.js';
+import { registerDeleteFile } from './tools/delete_file.js';
+import { registerCreateWorkspace } from './tools/create_workspace.js';
+import { registerApplyProblemToWorkspace } from './tools/apply_problem_to_workspace.js';
+import { registerSaveProblemToLibrary } from './tools/save_problem_to_library.js';
+import { registerEditProblem } from './tools/edit_problem.js';
+import { registerDeleteProblem } from './tools/delete_problem.js';
+async function main() {
+    const env = readEnv();
+    const client = createClient(env);
+    const server = new McpServer({
+        name: 'typelets-mcp',
+        version: '0.0.1',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Phase 1 read-only tools. Each module owns its own input schema,
+    // description, and handler so adding/removing tools is a single-file
+    // change and the entry stays a flat registration list.
+    registerListWorkspaces(server, client, env);
+    registerGetWorkspace(server, client, env);
+    registerListWorkspaceFiles(server, client, env);
+    registerReadWorkspaceFile(server, client, env);
+    registerListProblems(server, client, env);
+    registerGetProblem(server, client, env);
+    registerListRecordings(server, client, env);
+    registerListPendingInvites(server, client, env);
+    // Phase 2 write tools (profile-gated inside each register function).
+    registerCreateFile(server, client, env);
+    registerUpdateFile(server, client, env);
+    registerDeleteFile(server, client, env);
+    registerCreateWorkspace(server, client, env);
+    registerApplyProblemToWorkspace(server, client, env);
+    registerSaveProblemToLibrary(server, client, env);
+    registerEditProblem(server, client, env);
+    registerDeleteProblem(server, client, env);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr (stdout is the MCP transport). Surfaces in the client's
+    // server log so the user can confirm the profile they're running.
+    process.stderr.write(`typelets-mcp running. profile=${env.profile} api=${env.apiUrl}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`typelets-mcp failed to start: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,+BAA+B,EAAE,MAAM,uCAAuC,CAAC;AACxF,OAAO,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAEjC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,OAAO;KACjB,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,kEAAkE;IAClE,qEAAqE;IACrE,uDAAuD;IACvD,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5C,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1C,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAChD,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/C,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1C,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5C,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAEhD,qEAAqE;IACrE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7C,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACrD,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAClD,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACzC,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,wEAAwE;IACxE,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCAAiC,GAAG,CAAC,OAAO,QAAQ,GAAG,CAAC,MAAM,IAAI,CACnE,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCAAiC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACtF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/profile.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Profile-aware filtering for outbound tool responses.
+ *
+ * The `candidate` profile strips fields the candidate must not see even
+ * if their auth token would let them: hidden tests, rubric content,
+ * scores, solution files. The `interviewer` profile is a pass-through.
+ *
+ * The point is defense in depth. The API already enforces these
+ * boundaries on a per-role basis, but the candidate profile is a
+ * second gate the user opts into when they don't want their AI
+ * assistant ingesting answer-key content along with the prompt.
+ */
+import type { Env } from './env.js';
+export interface ProblemDetailLike {
+    id: string;
+    title: string;
+    prompt: string;
+    difficulty: string;
+    category: string;
+    tags: string[];
+    /** Interviewer-only. Removed in candidate profile. */
+    rubric?: string | null;
+    /** Interviewer-only. Removed in candidate profile. */
+    criteria?: {
+        name: string;
+        description: string;
+    }[];
+    /** Interviewer-only. Hidden tests stripped; visible tests remain. */
+    tests?: {
+        input: string;
+        expectedOutput: string;
+        visible: boolean;
+    }[];
+    starters?: Record<string, unknown>;
+    /** Interviewer-only. Removed entirely in candidate profile. */
+    solution?: Record<string, unknown>;
+}
+/**
+ * Names of tools that the candidate profile MUST NOT register. The
+ * server skips registration for these when `env.profile === 'candidate'`,
+ * so the candidate's host LLM never sees them in `listTools` and cannot
+ * try to invoke them.
+ *
+ * Per-file CRUD (create_file, update_file, delete_file) is allowed for
+ * candidates: they have editor role inside their own interview
+ * workspace and need to be able to modify their files.
+ */
+export declare const INTERVIEWER_ONLY_TOOLS: ReadonlySet<string>;
+export declare function toolAllowedForProfile(toolName: string, profile: Env['profile']): boolean;
+export declare function filterProblemForProfile<T extends ProblemDetailLike>(problem: T, env: Env): T;

package/dist/profile.js

@@ -0,0 +1,35 @@
+/**
+ * Names of tools that the candidate profile MUST NOT register. The
+ * server skips registration for these when `env.profile === 'candidate'`,
+ * so the candidate's host LLM never sees them in `listTools` and cannot
+ * try to invoke them.
+ *
+ * Per-file CRUD (create_file, update_file, delete_file) is allowed for
+ * candidates: they have editor role inside their own interview
+ * workspace and need to be able to modify their files.
+ */
+export const INTERVIEWER_ONLY_TOOLS = new Set([
+    'create_workspace',
+    'apply_problem_to_workspace',
+    'save_problem_to_library',
+    'edit_problem',
+    'delete_problem',
+]);
+export function toolAllowedForProfile(toolName, profile) {
+    if (profile === 'interviewer')
+        return true;
+    return !INTERVIEWER_ONLY_TOOLS.has(toolName);
+}
+export function filterProblemForProfile(problem, env) {
+    if (env.profile === 'interviewer')
+        return problem;
+    const next = { ...problem };
+    delete next.rubric;
+    delete next.criteria;
+    delete next.solution;
+    if (Array.isArray(next.tests)) {
+        next.tests = next.tests.filter((t) => t.visible === true);
+    }
+    return next;
+}
+//# sourceMappingURL=profile.js.map

package/dist/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IACjE,kBAAkB;IAClB,4BAA4B;IAC5B,yBAAyB;IACzB,cAAc;IACd,gBAAgB;CACjB,CAAC,CAAC;AAEH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,OAAuB;IAC7E,IAAI,OAAO,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,CAAC,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAAU,EACV,GAAQ;IAER,IAAI,GAAG,CAAC,OAAO,KAAK,aAAa;QAAE,OAAO,OAAO,CAAC;IAClD,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAC5B,OAAO,IAAI,CAAC,MAAM,CAAC;IACnB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACrB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACrB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/_shared.d.ts

@@ -0,0 +1,17 @@
+export interface ToolContentItem {
+    type: 'text';
+    text: string;
+}
+export interface ToolResult {
+    [x: string]: unknown;
+    content: ToolContentItem[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}
+/** Build a successful tool response. `summary` is human-readable; `data`
+ *  is the structured payload the model should reason over. */
+export declare function ok(summary: string, data: unknown): ToolResult;
+/** Build an error tool response. Maps TypeletsApiError to a readable
+ *  message and preserves the underlying status so the model can branch
+ *  on it (e.g. 404 -> ask the user for a different id). */
+export declare function fail(err: unknown): ToolResult;

package/dist/tools/_shared.js

@@ -0,0 +1,55 @@
+/**
+ * Helpers shared across tool handlers.
+ *
+ * The MCP tool response shape is `{ content: ContentItem[], isError?: boolean }`.
+ * Every Phase 1 tool returns the same structure:
+ *   - a `text` block carrying a short human-readable summary
+ *   - a `text` block carrying the JSON payload, fenced so the host LLM
+ *     can pick it out cleanly
+ *
+ * Keeping the shape uniform means downstream LLMs can rely on the
+ * "first line is summary, fenced block is data" contract without
+ * tool-specific parsing.
+ */
+import { TypeletsApiError } from '../client.js';
+/** Build a successful tool response. `summary` is human-readable; `data`
+ *  is the structured payload the model should reason over. */
+export function ok(summary, data) {
+    return {
+        content: [
+            { type: 'text', text: summary },
+            { type: 'text', text: `\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\`` },
+        ],
+        structuredContent: { result: data },
+    };
+}
+/** Build an error tool response. Maps TypeletsApiError to a readable
+ *  message and preserves the underlying status so the model can branch
+ *  on it (e.g. 404 -> ask the user for a different id). */
+export function fail(err) {
+    if (err instanceof TypeletsApiError) {
+        const bodyDetails = err.body !== null &&
+            typeof err.body === 'object' &&
+            'details' in err.body &&
+            Array.isArray(err.body.details)
+            ? `\nValidation details: ${JSON.stringify(err.body.details)}`
+            : '';
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Typelets API error ${err.status}: ${err.message}${bodyDetails}`,
+                },
+            ],
+            structuredContent: { error: { status: err.status, message: err.message, body: err.body } },
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: 'text', text: `tool failed: ${message}` }],
+        structuredContent: { error: { message } },
+    };
+}
+//# sourceMappingURL=_shared.js.map

package/dist/tools/_shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../src/tools/_shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAgBhD;8DAC8D;AAC9D,MAAM,UAAU,EAAE,CAAC,OAAe,EAAE,IAAa;IAC/C,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE;YAC/B,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,UAAU,EAAE;SACjF;QACD,iBAAiB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;KACpC,CAAC;AACJ,CAAC;AAED;;2DAE2D;AAC3D,MAAM,UAAU,IAAI,CAAC,GAAY;IAC/B,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;QACpC,MAAM,WAAW,GACf,GAAG,CAAC,IAAI,KAAK,IAAI;YACjB,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;YAC5B,SAAS,IAAI,GAAG,CAAC,IAAI;YACrB,KAAK,CAAC,OAAO,CAAE,GAAG,CAAC,IAAgC,CAAC,OAAO,CAAC;YAC1D,CAAC,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAE,GAAG,CAAC,IAAgC,CAAC,OAAO,CAAC,EAAE;YAC1F,CAAC,CAAC,EAAE,CAAC;QACT,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,sBAAsB,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,OAAO,GAAG,WAAW,EAAE;iBACvE;aACF;YACD,iBAAiB,EAAE,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE;SAC3F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,OAAO,EAAE,EAAE,CAAC;QAC5D,iBAAiB,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE;KAC1C,CAAC;AACJ,CAAC"}

package/dist/tools/apply_problem_to_workspace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * apply_problem_to_workspace: apply a library problem to an interview workspace.
+ *
+ * Interviewer-only. Materializes the problem's starter + test files into the
+ * workspace tree, sets the interview prompt/rubric/criteria/tests on the
+ * workspace, and REPLACES any previously applied files. This is destructive.
+ * a co-editor's in-progress work may be clobbered.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TypeletsClient } from '../client.js';
+import type { Env } from '../env.js';
+export declare function registerApplyProblemToWorkspace(server: McpServer, client: TypeletsClient, env: Env): void;

package/dist/tools/apply_problem_to_workspace.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { toolAllowedForProfile } from '../profile.js';
+import { ok, fail } from './_shared.js';
+export function registerApplyProblemToWorkspace(server, client, env) {
+    // Profile gate: keep the string in sync with INTERVIEWER_ONLY_TOOLS in ../profile.ts.
+    if (!toolAllowedForProfile('apply_problem_to_workspace', env.profile))
+        return;
+    server.registerTool('apply_problem_to_workspace', {
+        title: 'Apply a library problem to an interview workspace',
+        description: 'Apply a library problem to an interview workspace. Materializes the problem\'s starter files ' +
+            'and test files into the workspace tree and copies the prompt, rubric, criteria, and test cases ' +
+            'onto the workspace. Existing candidate work in the workspace is REPLACED: any previously ' +
+            'applied starter files are removed and the new ones are written in a single atomic pass. ' +
+            'Destructive. Confirm before invoking. Errors: 404 if the workspace or problem is not found; ' +
+            '403 if the caller is not owner/admin/interviewer of the workspace.',
+        inputSchema: {
+            workspaceId: z.string().min(1).describe('The workspace id from list_workspaces or create_workspace. Typically an interview-mode workspace. The API does not enforce this, but applying to a general workspace populates interview fields that the general-mode UI does not surface.'),
+            problemId: z.string().min(1).describe('The problem id or slug from list_problems. Accepts either the cuid or the slug.'),
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ workspaceId, problemId }) => {
+        try {
+            const result = await client.post(`/workspaces/${encodeURIComponent(workspaceId)}/interview/problem`, { problemId });
+            return ok(`Applied problem ${problemId} to workspace ${workspaceId}.`, { workspace: result.workspace });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}
+//# sourceMappingURL=apply_problem_to_workspace.js.map

package/dist/tools/apply_problem_to_workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply_problem_to_workspace.js","sourceRoot":"","sources":["../../src/tools/apply_problem_to_workspace.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAaxC,MAAM,UAAU,+BAA+B,CAAC,MAAiB,EAAE,MAAsB,EAAE,GAAQ;IACjG,sFAAsF;IACtF,IAAI,CAAC,qBAAqB,CAAC,4BAA4B,EAAE,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO;IAE9E,MAAM,CAAC,YAAY,CACjB,4BAA4B,EAC5B;QACE,KAAK,EAAE,mDAAmD;QAC1D,WAAW,EACT,+FAA+F;YAC/F,iGAAiG;YACjG,2FAA2F;YAC3F,0FAA0F;YAC1F,8FAA8F;YAC9F,oEAAoE;QACtE,WAAW,EAAE;YACX,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4OAA4O,CAAC;YACrR,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iFAAiF,CAAC;SACzH;QACD,WAAW,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE;KACvC,EACD,KAAK,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE;QACnC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAC9B,eAAe,kBAAkB,CAAC,WAAW,CAAC,oBAAoB,EAClE,EAAE,SAAS,EAAE,CACd,CAAC;YACF,OAAO,EAAE,CACP,mBAAmB,SAAS,iBAAiB,WAAW,GAAG,EAC3D,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAChC,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/create_file.d.ts

@@ -0,0 +1,11 @@
+/**
+ * create_file: create a new file at a path in a workspace.
+ *
+ * Available to both interviewer and candidate profiles. Candidates have
+ * editor role in their own interview workspace and need to create files.
+ * Intermediate folders are created automatically; returns the new file id.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TypeletsClient } from '../client.js';
+import type { Env } from '../env.js';
+export declare function registerCreateFile(server: McpServer, client: TypeletsClient, env: Env): void;