@testplanit/mcp-server 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,490 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface EnvConfig {
+    apiToken: string;
+    apiUrl: string;
+}
+/**
+ * Parse and validate the MCP server's environment.
+ *
+ * Throws a zod validation error when:
+ *  - `TESTPLANIT_API_TOKEN` is missing or does not start with `tpi_`
+ *  - `TESTPLANIT_API_URL` is set but is not a valid URL (omitting it uses the SaaS default)
+ *
+ * The returned `apiUrl` is normalized (trailing slash stripped).
+ */
+declare function parseEnv(env: NodeJS.ProcessEnv): EnvConfig;
+
+/**
+ * Response shape from `GET /api/auth/whoami` — locked in lockstep with
+ * plan 05-02. Field semantics (frozen contract):
+ *  - `readOnly === scopes.includes("mode:read")`
+ *  - `isAgent  === scopes.includes("client:mcp")`
+ */
+interface WhoamiUser {
+    id: string;
+    name: string | null;
+    email: string;
+    scopes: string[];
+    readOnly: boolean;
+    isAgent: boolean;
+}
+/**
+ * Result of `validateToken()`.
+ *
+ * The failure variant carries `code` (upstream errorCode such as
+ * `READ_ONLY_TOKEN`, `EXPIRED_TOKEN`) and `statusCode` (HTTP status) so
+ * downstream tools — plan 05-07's `whoami` and Phase 6+ write tools —
+ * can construct `TestPlanItHttpError` without re-parsing the message
+ * string. This shape is locked at plan 05-06 and consumed directly by
+ * plan 05-07; do NOT widen retroactively.
+ */
+type ValidateResult = {
+    ok: true;
+    user: WhoamiUser;
+} | {
+    ok: false;
+    message: string;
+    code?: string;
+    statusCode?: number;
+};
+/**
+ * Error class carrying upstream HTTP status + errorCode for tool handlers.
+ * Plan 05-07 throws this from the `whoami` tool when validateToken returns
+ * `ok: false` so the MCP error mapping retains the upstream codes.
+ */
+declare class TestPlanItHttpError extends Error {
+    statusCode?: number;
+    code?: string;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        code?: string;
+    });
+}
+/**
+ * Returns at most the `tpi_xxxx`-style 8-character prefix of the token for
+ * safe diagnostics. Never returns the full token. T-05-06 mitigation.
+ */
+declare function redactToken(token: string): string;
+/**
+ * Probe `GET /api/auth/whoami` with the configured Bearer token.
+ *
+ * Returns `{ ok: true, user }` on a 200 response with a valid JSON body.
+ * Returns `{ ok: false, message, code?, statusCode? }` on any non-2xx,
+ * unparseable body, or transport failure. The error message NEVER contains
+ * the raw token — only the redacted prefix appears (T-05-06).
+ */
+declare function validateToken(env: EnvConfig): Promise<ValidateResult>;
+
+interface RunDeps {
+    parseEnvImpl: (env: NodeJS.ProcessEnv) => EnvConfig;
+    validateImpl: (env: EnvConfig) => Promise<ValidateResult>;
+    createServerImpl: (deps: {
+        env: EnvConfig;
+        user: WhoamiUser;
+    }) => McpServer;
+    connectImpl: (server: McpServer) => Promise<void>;
+    errLog: (...args: unknown[]) => void;
+    exitImpl: (code: number) => void;
+}
+/**
+ * Default implementations wiring the real env, http, and stdio transport.
+ * Overridden in tests to assert exit codes + serial order without spawning
+ * a real subprocess.
+ */
+declare const defaultRunDeps: RunDeps;
+/**
+ * Bootstrap the MCP server in strict serial order:
+ *   parseEnv → validateToken → createServer → connect (stdio)
+ *
+ * Bad env or bad token exits with code 1 BEFORE any transport connect.
+ * All diagnostics go through `errLog` (defaults to `console.error`); raw
+ * token values are NEVER logged — only the redacted `tpi_xxxx` prefix
+ * appears in error messages (T-05-06).
+ */
+declare function runServer(deps?: RunDeps): Promise<void>;
+
+/**
+ * Dependencies the CLI bootstrap (cli.ts `runServer`) injects into
+ * `createServer`.
+ *
+ * `user` is the `WhoamiUser` resolved by the bootstrap probe; it is
+ * intentionally retained on the deps contract even though Phase 5's
+ * production tools (`whoami`) re-fetch live data on every call. Future
+ * tools may use `user` for static-shape decisions (e.g., gating Phase 6+
+ * write tools on `!user.readOnly` at registration time).
+ */
+interface ServerDeps {
+    env: EnvConfig;
+    user: WhoamiUser;
+}
+/**
+ * Create an MCP server instance for TestPlanIt.
+ *
+ * Plan 05-06 registered a placeholder smoke tool so the
+ * `InMemoryTransport` handshake test had something to find. Plan 05-07
+ * replaces that with the production `whoami` tool, registered through the
+ * central `registerAll` registry — Phase 6+ tools plug into the registry
+ * without further edits to this file.
+ */
+declare function createServer(deps: ServerDeps): McpServer;
+
+/**
+ * MCP tool-result error envelope.
+ *
+ * The SDK accepts either a thrown exception (which it auto-converts) OR an
+ * explicit return value with `isError: true`. We use the explicit form so
+ * tool handlers control the agent-visible message verbatim — no SDK
+ * stack-trace leakage and no opaque "An error occurred" wrappers.
+ *
+ * Reference: 05-RESEARCH.md § Don't Hand-Roll row "Tool error formatting".
+ */
+interface ToolErrorResult {
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    [x: string]: unknown;
+}
+/**
+ * Translate any thrown error from a tool handler into the MCP tool-result
+ * error envelope. Three paths:
+ *
+ *  1. `TestPlanItHttpError` with a known `code`: friendly template, code
+ *     appended in parentheses for log-grep traceability.
+ *  2. `TestPlanItHttpError` with an unknown / missing code: generic
+ *     "Request failed: <message> (HTTP <status>)" fallback.
+ *  3. Any other `Error`: "Network or runtime error: <message>" fallback.
+ *  4. Non-Error throwable: "Unknown error".
+ *
+ * The friendly templates are fixed strings, NOT echoes of `err.message`,
+ * so a token-bearing message accidentally constructed upstream cannot leak
+ * the raw token through this layer (T-05-06 defense in depth). The fallback
+ * paths DO interpolate `err.message`, so the final text is run through
+ * `redactTokens` as a belt-and-suspenders scrub (WR-03).
+ */
+declare function mapHttpErrorToToolResult(err: unknown): ToolErrorResult;
+
+interface WhoamiDeps {
+    env: EnvConfig;
+}
+/**
+ * Register the `whoami` MCP tool — the production replacement for plan
+ * 05-06's smoke tool.
+ *
+ * The tool re-fetches `GET /api/auth/whoami` on every invocation (NOT
+ * cached from the bootstrap probe) so scope changes — particularly the
+ * read-only flag — reflect immediately.
+ *
+ * On failure, the handler consumes the wider `ValidateResult` shape locked
+ * in plan 05-06 by reading `probe.code` and `probe.statusCode` directly,
+ * NOT by string-parsing `probe.message`. The constructed
+ * `TestPlanItHttpError` is then translated by `mapHttpErrorToToolResult`
+ * which knows how to format `READ_ONLY_TOKEN` (T-05-01 mitigation) and the
+ * other 7 host errorCodes.
+ *
+ * The description starts with `"Debug:"` so well-behaved agents
+ * deprioritize this tool versus the data tools shipping in Phase 6+.
+ */
+declare function registerWhoami(server: McpServer, deps: WhoamiDeps): void;
+
+interface CasesListDeps {
+    env: EnvConfig;
+}
+
+interface CasesGetDeps {
+    env: EnvConfig;
+}
+
+interface CasesCreateDeps {
+    env: EnvConfig;
+}
+
+interface CasesUpdateDeps {
+    env: EnvConfig;
+}
+
+interface CasesDeleteDeps {
+    env: EnvConfig;
+}
+
+type CasesDeps = CasesListDeps & CasesGetDeps & CasesCreateDeps & CasesUpdateDeps & CasesDeleteDeps;
+declare function registerCases(server: McpServer, deps: CasesDeps): void;
+
+interface FoldersListDeps {
+    env: EnvConfig;
+}
+
+interface FoldersGetDeps {
+    env: EnvConfig;
+}
+
+interface FoldersCreateDeps {
+    env: EnvConfig;
+}
+
+interface FoldersUpdateDeps {
+    env: EnvConfig;
+}
+
+interface FoldersDeleteDeps {
+    env: EnvConfig;
+}
+
+type FoldersDeps = FoldersListDeps & FoldersGetDeps & FoldersCreateDeps & FoldersUpdateDeps & FoldersDeleteDeps;
+declare function registerFolders(server: McpServer, deps: FoldersDeps): void;
+
+interface TagsListDeps {
+    env: EnvConfig;
+}
+
+type TagsDeps = TagsListDeps;
+declare function registerTags(server: McpServer, deps: TagsDeps): void;
+
+interface ProjectsListDeps {
+    env: EnvConfig;
+}
+
+type ProjectsDeps = ProjectsListDeps;
+declare function registerProjects(server: McpServer, deps: ProjectsDeps): void;
+
+interface RunsListDeps {
+    env: EnvConfig;
+}
+
+interface RunsGetDeps {
+    env: EnvConfig;
+}
+
+interface RunsCasesListDeps {
+    env: EnvConfig;
+}
+
+interface RunResultsListDeps {
+    env: EnvConfig;
+}
+
+interface RunResultsGetDeps {
+    env: EnvConfig;
+}
+
+interface RunResultsCreateDeps {
+    env: EnvConfig;
+}
+
+type RunResultsDeps = RunResultsListDeps & RunResultsGetDeps & RunResultsCreateDeps;
+
+interface RunsCreateDeps {
+    env: EnvConfig;
+}
+
+interface RunsUpdateDeps {
+    env: EnvConfig;
+}
+
+interface RunsCasesAddDeps {
+    env: EnvConfig;
+}
+
+type RunsDeps = RunsListDeps & RunsGetDeps & RunsCasesListDeps & RunResultsDeps & RunsCreateDeps & RunsUpdateDeps & RunsCasesAddDeps;
+declare function registerRuns(server: McpServer, deps: RunsDeps): void;
+
+interface SessionsListDeps {
+    env: EnvConfig;
+}
+
+interface SessionsGetDeps {
+    env: EnvConfig;
+}
+
+interface SessionResultsListDeps {
+    env: EnvConfig;
+}
+
+interface SessionResultsGetDeps {
+    env: EnvConfig;
+}
+
+/**
+ * Aggregate dependencies for the SESS-03 / SESS-04 session-result read tools.
+ * Both tools share the same EnvConfig; this intersection lets the parent
+ * `registerSessions` pass a single deps object (mirrors the runs/results
+ * pattern from plan 07-03).
+ */
+type SessionResultsDeps = SessionResultsListDeps & SessionResultsGetDeps;
+
+interface SessionsFindingsDeps {
+    env: EnvConfig;
+}
+
+interface SessionsCreateDeps {
+    env: EnvConfig;
+}
+
+interface SessionsUpdateDeps {
+    env: EnvConfig;
+}
+
+type SessionsDeps = SessionsListDeps & SessionsGetDeps & SessionResultsDeps & SessionsFindingsDeps & SessionsCreateDeps & SessionsUpdateDeps;
+declare function registerSessions(server: McpServer, deps: SessionsDeps): void;
+
+interface CodeRepositoriesListDeps {
+    env: EnvConfig;
+}
+
+/**
+ * Aggregate dependencies for the Phase 8 code-repositories read tools. Only
+ * one tool today (`testplanit_code_repositories_list`); aliasing rather than
+ * intersecting keeps room to add `_get` etc. via union extension when the
+ * single-row-per-project invariant relaxes.
+ *
+ * Registry wiring into `tools/index.ts` is intentionally deferred to plan
+ * 08-05 (wave 3) so plans 08-01..08-04 can run in parallel without touching
+ * the same file.
+ */
+type CodeRepositoriesDeps = CodeRepositoriesListDeps;
+
+interface IssuesFindByKeyDeps {
+    env: EnvConfig;
+}
+
+interface IssuesListDeps {
+    env: EnvConfig;
+}
+
+interface IssuesGetDeps {
+    env: EnvConfig;
+}
+
+interface IssuesListLinksDeps {
+    env: EnvConfig;
+}
+
+interface IssuesLinkDeps {
+    env: EnvConfig;
+}
+
+type IssuesDeps = IssuesFindByKeyDeps & IssuesListDeps & IssuesGetDeps & IssuesListLinksDeps & IssuesLinkDeps;
+
+interface RepositoryCaseLinksListDeps {
+    env: EnvConfig;
+}
+
+type RepositoryCaseLinksDeps = RepositoryCaseLinksListDeps;
+
+interface MilestonesListDeps {
+    env: EnvConfig;
+}
+
+interface MilestonesGetDeps {
+    env: EnvConfig;
+}
+
+interface MilestoneTypesListDeps {
+    env: EnvConfig;
+}
+
+interface MilestonesCreateDeps {
+    env: EnvConfig;
+}
+
+interface MilestonesUpdateDeps {
+    env: EnvConfig;
+}
+
+type MilestonesDeps = MilestonesListDeps & MilestonesGetDeps & MilestoneTypesListDeps & MilestonesCreateDeps & MilestonesUpdateDeps;
+
+/**
+ * Aggregate dependencies for every tool registered by
+ * `@testplanit/mcp-server`. The intersection widens with each new domain;
+ * adding a new domain barrel means adding the matching `& <Domain>Deps`
+ * here so all registered tools see the same single deps object at runtime.
+ */
+type ToolRegistryDeps = WhoamiDeps & CasesDeps & FoldersDeps & TagsDeps & ProjectsDeps & RunsDeps & SessionsDeps & CodeRepositoriesDeps & IssuesDeps & RepositoryCaseLinksDeps & MilestonesDeps;
+/**
+ * Register every tool shipped by `@testplanit/mcp-server`.
+ *
+ * Tools are grouped by domain: whoami (debug/identity), cases, folders,
+ * tags, projects (agent context disambiguation), runs, sessions,
+ * code-repositories, issues, repository-case-links, and milestones
+ * (milestones_list, milestones_get, milestone_types_list).
+ */
+declare function registerAll(server: McpServer, deps: ToolRegistryDeps): void;
+
+/**
+ * Internal ZenStack RPC client.
+ *
+ * Replicates the dispatch pattern from `packages/api/src/client.ts` so
+ * `@testplanit/mcp-server` has NO dependency on `@testplanit/api` (D-01).
+ *
+ * Read operations use GET with `?q=encodeURIComponent(JSON.stringify(body))`.
+ * Write operations use POST/PATCH/DELETE with the JSON body.
+ *
+ * Errors:
+ *  - Non-2xx → throws TestPlanItHttpError with statusCode + (when present) code
+ *    parsed from the response body. Critical: HTTP 422 may be a route.ts
+ *    remap of a ZenStack 403 (policy denial) or 404 (P2025 missing record).
+ *    The error mapper in errors.ts disambiguates by message content.
+ *  - 2xx with `error` envelope → throws TestPlanItHttpError with envelope code.
+ *  - 2xx with `data` → returns `data` unwrapped.
+ *
+ * Soft-delete invariant: callers MUST use `update` with `{ data: { isDeleted: true } }`
+ * for soft-delete, NEVER the `delete` or `deleteMany` operations (T-06-06).
+ */
+declare function zenstack<T>(model: string, operation: string, body: unknown, env: EnvConfig): Promise<T>;
+/**
+ * Name → ID lookup via `/api/cli/lookup` (D-02).
+ *
+ * NOT all entity types are supported — see VERIFIED type union below. Notably,
+ * `CaseField` is NOT a lookup type; resolve custom fields via
+ * `zenstack("caseFields", "findMany", { where: { displayName: ..., isDeleted: false } })`.
+ *
+ * The `state` lookup type hardcodes `WorkflowScope.RUNS` on the host
+ * (`/api/cli/lookup/route.ts` line 106). For case workflow state, use
+ * `resolveCaseWorkflowState` instead.
+ */
+type LookupType = "project" | "state" | "config" | "milestone" | "tag" | "folder" | "testRun";
+interface LookupRequest {
+    type: LookupType;
+    name: string;
+    projectId?: number;
+    createIfMissing?: boolean;
+}
+interface LookupResponse {
+    id: number;
+    name: string;
+    created?: boolean;
+}
+declare function lookup(options: LookupRequest, env: EnvConfig): Promise<LookupResponse>;
+/**
+ * Resolve the single active repository for a project. Cases and folders
+ * require `repositoryId` on create; the active repository is selected by
+ * the first row matching `isActive=true, isDeleted=false, isArchived=false`.
+ *
+ * Throws TestPlanItHttpError with statusCode 422 (host-class "operation
+ * refused / missing context") when no active repository exists, with a
+ * human-readable message instructing the user to initialize the repo via
+ * the TestPlanIt UI. The 422 status routes the error through the same
+ * `mapHttpErrorToToolResult` branch as host-side missing-record errors.
+ */
+declare function resolveActiveRepository(projectId: number, env: EnvConfig): Promise<number>;
+/**
+ * Resolve a default template assigned to the project (cases require
+ * `templateId` per RepositoryCases.templateId being non-nullable —
+ * VERIFIED in schema.zmodel).
+ */
+declare function resolveDefaultTemplate(projectId: number, env: EnvConfig): Promise<number>;
+/**
+ * Resolve a workflow state for the CASES scope (NOT runs). Pass `name` to
+ * select by name; omit to take the first by `order asc`.
+ *
+ * Cannot use `/api/cli/lookup` — that endpoint hardcodes
+ * `WorkflowScope.RUNS` (see /api/cli/lookup/route.ts line 106).
+ */
+declare function resolveCaseWorkflowState(projectId: number, env: EnvConfig, name?: string): Promise<{
+    id: number;
+    name: string;
+}>;
+
+export { type CasesDeps, type EnvConfig, type FoldersDeps, type LookupRequest, type LookupResponse, type LookupType, type ProjectsDeps, type RunDeps, type RunsDeps, type ServerDeps, type SessionsDeps, type TagsDeps, TestPlanItHttpError, type ToolErrorResult, type ToolRegistryDeps, type ValidateResult, type WhoamiDeps, type WhoamiUser, createServer, defaultRunDeps, lookup, mapHttpErrorToToolResult, parseEnv, redactToken, registerAll, registerCases, registerFolders, registerProjects, registerRuns, registerSessions, registerTags, registerWhoami, resolveActiveRepository, resolveCaseWorkflowState, resolveDefaultTemplate, runServer, validateToken, zenstack };