@antasphere/chassis-server 1.0.0

package/src/mcp/projects.ts

@@ -0,0 +1,480 @@
+import { z } from 'zod';
+import {
+  PROJECT_METADATA_MAX_LENGTH,
+  projectRoleSchema,
+  projectsArchivedFilterSchema
+} from '@antasphere/chassis-contract';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { deny, jsonText, wrapToolErrors, type ErrorHints, type ToolTextResult } from './errors.js';
+import {
+  callApi,
+  forWorkspace,
+  pageQuery,
+  type McpScopes,
+  type McpToolContext,
+  type ScopeCheck
+} from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+
+/**
+ * The eleven PROJECT tools, registered by the chassis beside
+ * `<toolPrefix>whoami` — a project is a chassis concept (a subgroup of a
+ * workspace with its own members and roles), so every tool an instance serves
+ * over it is the chassis', not a tool's. Each one is a thin shim over the
+ * instance's own /api/v1/projects called IN-PROCESS with the caller's bearer
+ * forwarded verbatim: no privileged path, no MCP-only endpoint, and the API's
+ * fail-closed scope allowlist plus the tiered project answer (404 before 403
+ * before 409) apply unchanged.
+ *
+ * The conventions of the set are the chassis' (server.ts): reads carry
+ * `readOnlyHint: true` and pre-check the read scope, writes describe
+ * themselves confirm-first and pre-check the write scope, and every tool
+ * takes the same optional `workspace` argument.
+ *
+ * Nothing here names a tool, a brand or a domain: the prefix arrives as
+ * `identity.toolPrefix` and the wire shapes are the contract's.
+ */
+
+/**
+ * What a project IS, in the words an agent that has never seen one needs. It
+ * opens every description in the set, so a model reading `tools/list` learns
+ * the concept once from whichever tool it looks at first.
+ */
+const WHAT_IS_A_PROJECT =
+  'A project is a subgroup of an organization (workspace): a named space with its own members, ' +
+  'used to group work and who may touch it.';
+
+/**
+ * The three roles, each containing the one before it. Written out wherever a
+ * role is chosen or shown, because the whole authorization story of the
+ * surface is in it.
+ */
+const ROLE_LADDER_BODY =
+  '`viewer` reads the project and what is linked to it; `editor` may also write what is linked to ' +
+  'it; `manager` may also rename the project, archive it, and manage its members. An organization ' +
+  'owner or admin acts as a manager on every project.';
+const ROLE_LADDER = `Roles, each containing the one before it: ${ROLE_LADDER_BODY}`;
+
+/** How an archived project behaves, and the one way back. */
+const ARCHIVED_RULE =
+  'An archived project is out of the default list and read-only: every change is refused until it ' +
+  'is brought back. A project is never deleted.';
+
+/**
+ * The project codes, turned from an API code into a sentence a model can act
+ * on, for the tool whose prefix is given: a hint that names a tool names it
+ * as it is registered (`<toolPrefix>list_project_members`), or the model
+ * follows it to a tool that does not exist. Merged into the instance's hint
+ * table (`mergeErrorHints`) so a refusal reads as words rather than as a
+ * code. The role a refusal needs is the message's, never assumed here: a
+ * tool's own route over a project may gate on `editor` where every chassis
+ * route gates on `manager`.
+ *
+ * Every key here is a code only the project routes answer. `not_found` is
+ * DELIBERATELY absent: it is the whole instance's code, a tool already words
+ * it for its own domain (and its hint wins, `buildMcpServer`), and a sentence
+ * about projects on the answer of every other 404 would be worse than none.
+ * The tiered answer is stated in the descriptions instead, where it belongs:
+ * a project you cannot read answers not found, so being refused is not proof
+ * that it exists.
+ */
+export function projectErrorHints(toolPrefix: string): ErrorHints {
+  const t = (name: string) => `${toolPrefix}${name}`;
+  return {
+    insufficient_project_role:
+      'Your role on this project is below what this needs (the message names the role; the chassis ' +
+      'routes need manager). Ask a project manager, or an owner or admin of the organization, to make ' +
+      'the change or to raise your role.',
+    project_archived:
+      'This project is archived, so it is read-only. Bring it back first (archive the project with ' +
+      'archived set to false), then try again.',
+    project_not_archived: 'This project is not archived, so there is nothing to bring back.',
+    member_not_found:
+      `No such member. On ${t('add_project_member')}: nobody in the organization matches, and a project ` +
+      'member must already be an active organization member, named by the exact user id or email ' +
+      `address they joined with. On ${t('set_project_member_role')} or ${t('remove_project_member')}: ` +
+      `this person is not on the project (${t('list_project_members')} shows who is).`,
+    already_member:
+      'This person or team is already a member of the project — change the role instead of adding ' +
+      'them again.',
+    team_not_found:
+      `No such team. On ${t('add_project_member')}: no team of the organization has this id ` +
+      `(${t('list_teams')} lists them). On ${t('set_project_team_role')} or ${t('remove_project_team')}: ` +
+      `this team is not on the project (${t('list_project_members')} shows who is).`,
+    guest_target:
+      'This person is an external guest invited to one item: their account is not this organization’s ' +
+      'to put on a project.',
+    guest_forbidden:
+      'This credential is a guest of the organization, invited to one item only, and guests take no ' +
+      'part in projects: nothing under the project tools answers it. Use a member’s credential.'
+  };
+}
+
+/**
+ * A project is named by an opaque id, never by its name: two projects may
+ * share a name, and the API answers 404 to whoever cannot read one.
+ */
+const projectIdInput = z
+  .uuid()
+  .describe('The project id, from the list or the create answer (never the project name).');
+
+const teamIdInput = z
+  .uuid()
+  .describe('The team id, as the teams list or the project member list reports it (never its name or slug).');
+
+const userIdInput = z
+  .string()
+  .min(1)
+  .max(200)
+  .describe('The member’s user id, as the member list reports it.');
+
+const roleInput = projectRoleSchema.describe(`The role on this project. ${ROLE_LADDER_BODY}`);
+
+const nameInput = z.string().min(1).max(200).describe('The project name, as people will read it.');
+
+const descriptionInput = z.string().max(2000).describe('A sentence or two on what the project is for.');
+
+const metadataInput = z
+  .record(z.string(), z.unknown())
+  .describe(
+    'Your own structured data on the project, a plain JSON object the server keeps verbatim ' +
+      `(at most ${PROJECT_METADATA_MAX_LENGTH} characters once serialized). It REPLACES the whole ` +
+      'object: read the project first and send the merged result, never a fragment.'
+  );
+
+/**
+ * Register the eleven project tools on a server. Called by `buildMcpServer`
+ * after `<toolPrefix>whoami` and before the tool's own set, so `tools/list`
+ * keeps one stable order: the chassis examples, whoami, the projects, the
+ * tool's own.
+ */
+export function registerProjectTools(
+  server: McpServer,
+  ctx: McpToolContext,
+  identity: McpIdentity,
+  scopes: McpScopes,
+  checkScope: ScopeCheck<string>,
+  hints: ErrorHints
+): void {
+  const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+  const prefix = identity.toolPrefix;
+
+  /** The read/write pre-check + the per-call workspace seam, in one step. */
+  const enter = (
+    scope: string,
+    workspace: string | undefined
+  ): { denied: ToolTextResult } | { ctx: McpToolContext } => {
+    const denied = checkScope(ctx.principal, scope);
+    return denied ? { denied } : { ctx: forWorkspace(ctx, workspace) };
+  };
+
+  const run = (
+    scope: string,
+    workspace: string | undefined,
+    body: (c: McpToolContext) => Promise<unknown>
+  ): Promise<ToolTextResult> => {
+    const entered = enter(scope, workspace);
+    if ('denied' in entered) return Promise.resolve(entered.denied);
+    return wrapToolErrors(async () => jsonText(await body(entered.ctx)), hints);
+  };
+
+  const jsonBody = (value: unknown): RequestInit => ({
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(value)
+  });
+
+  // ── Reads ────────────────────────────────────────────────────────────────
+
+  server.registerTool(
+    `${prefix}list_projects`,
+    {
+      description:
+        `List the projects you belong to in an organization, newest first. ${WHAT_IS_A_PROJECT} ` +
+        `${ROLE_LADDER} Returns { projects: [{ id, name, description, metadata, archivedAt, ` +
+        'createdBy, createdAt, updatedAt, myRole, memberCount }], nextCursor } — `myRole` is YOUR ' +
+        'role on that project, so it tells you in advance what you may do. When nextCursor is ' +
+        `non-null, call again with cursor set to it. By default only the live projects are listed; ` +
+        `${ARCHIVED_RULE}`,
+      inputSchema: {
+        workspace: workspaceInput,
+        archived: z
+          .union([z.boolean(), projectsArchivedFilterSchema])
+          .optional()
+          .describe(
+            'Which projects to list: false (the default) the live ones, true the archived ones, ' +
+              '"all" both.'
+          ),
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, archived, limit, cursor }) =>
+      run(scopes.read, workspace, (c) =>
+        // A model writes the natural boolean; the wire takes the enum.
+        callApi(
+          c,
+          pageQuery(
+            '/api/v1/projects',
+            { cursor, limit },
+            { archived: typeof archived === 'boolean' ? String(archived) : archived }
+          )
+        )
+      )
+  );
+
+  server.registerTool(
+    `${prefix}get_project`,
+    {
+      description:
+        `Read one project, with your own role on it. ${WHAT_IS_A_PROJECT} ${ROLE_LADDER} Returns ` +
+        '{ id, name, description, metadata, archivedAt, createdBy, createdAt, updatedAt, myRole, ' +
+        'memberCount }. A project you are not a member of answers "not found" whether or not it ' +
+        'exists — being refused is not proof that it is there.',
+      inputSchema: { workspace: workspaceInput, projectId: projectIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, projectId }) =>
+      run(scopes.read, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}`))
+  );
+
+  server.registerTool(
+    `${prefix}list_project_members`,
+    {
+      description:
+        `List a project's members and what each of them may do. ${ROLE_LADDER} A member is a ` +
+        'person or a team, told apart by `kind`: a person entry is { kind: "person", userId, email, ' +
+        'name, role, addedBy, createdAt }, a team entry { kind: "team", teamId, slug, name, ' +
+        'membersCount, hubTeamId, role, addedBy, createdAt }, and every member of a team holds the ' +
+        'team’s role; a person’s effective role is the highest of their own entry and their teams’. ' +
+        'Returns { members, nextCursor }; pass a person’s `userId` to the tools that change or remove ' +
+        `a member, a team’s \`teamId\` to ${prefix}set_project_team_role and ${prefix}remove_project_team.`,
+      inputSchema: {
+        workspace: workspaceInput,
+        projectId: projectIdInput,
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, projectId, limit, cursor }) =>
+      run(scopes.read, workspace, (c) =>
+        callApi(c, pageQuery(`/api/v1/projects/${projectId}/members`, { cursor, limit }))
+      )
+  );
+
+  // ── Writes ───────────────────────────────────────────────────────────────
+
+  server.registerTool(
+    `${prefix}create_project`,
+    {
+      description:
+        `Create a project in an organization — confirm with the user first (name included). ` +
+        `${WHAT_IS_A_PROJECT} You become its first manager, so you may then add members and set ` +
+        `their roles. ${ROLE_LADDER} Returns the new project, whose id is what every other ` +
+        'project tool takes.',
+      inputSchema: {
+        workspace: workspaceInput,
+        name: nameInput,
+        description: descriptionInput.optional(),
+        metadata: metadataInput.optional()
+      }
+    },
+    async ({ workspace, name, description, metadata }) =>
+      run(scopes.write, workspace, (c) =>
+        callApi(
+          c,
+          '/api/v1/projects',
+          jsonBody({
+            name,
+            ...(description !== undefined ? { description } : {}),
+            ...(metadata !== undefined ? { metadata } : {})
+          })
+        )
+      )
+  );
+
+  server.registerTool(
+    `${prefix}update_project`,
+    {
+      description:
+        'Change a project’s name, description or metadata — confirm with the user first. Needs the ' +
+        'manager role on the project (an organization owner or admin has it everywhere). Send only ' +
+        'the fields you are changing; `metadata` REPLACES the whole object, and a description set to ' +
+        `null clears it. ${ARCHIVED_RULE} Returns the project as it now is.`,
+      inputSchema: {
+        workspace: workspaceInput,
+        projectId: projectIdInput,
+        name: nameInput.optional(),
+        description: descriptionInput
+          .nullable()
+          .optional()
+          .describe('A sentence or two on what the project is for; null clears it.'),
+        metadata: metadataInput.optional()
+      }
+    },
+    async ({ workspace, projectId, name, description, metadata }) => {
+      if (name === undefined && description === undefined && metadata === undefined) {
+        return deny(
+          'Nothing to change: pass at least one of name, description or metadata. ' +
+            'Read the project first if you need its current values.'
+        );
+      }
+      return run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}`, {
+          ...jsonBody({
+            ...(name !== undefined ? { name } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(metadata !== undefined ? { metadata } : {})
+          }),
+          method: 'PATCH'
+        })
+      );
+    }
+  );
+
+  server.registerTool(
+    `${prefix}archive_project`,
+    {
+      description:
+        'Archive a project, or bring an archived one back — confirm with the user first. Needs the ' +
+        `manager role on the project. ${ARCHIVED_RULE} Nothing is lost: archiving is reversible, by ` +
+        'calling this same tool with `archived` set to false. Returns the project in its new state.',
+      inputSchema: {
+        workspace: workspaceInput,
+        projectId: projectIdInput,
+        archived: z
+          .boolean()
+          .optional()
+          .describe('true (the default) archives the project; false brings an archived one back.')
+      }
+      // No destructiveHint: a reversible, read-only switch is not a delete,
+      // and a host that gates destructive tools must not block the restore.
+    },
+    async ({ workspace, projectId, archived }) => {
+      const leg = archived === false ? 'unarchive' : 'archive';
+      return run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}/${leg}`, { method: 'POST' })
+      );
+    }
+  );
+
+  server.registerTool(
+    `${prefix}add_project_member`,
+    {
+      description:
+        'Put one of the organization’s own members on a project, with a role — confirm with the ' +
+        `user first. Needs the manager role on the project. ${ROLE_LADDER} Name the person by ` +
+        'either `userId` or `email`, and it must be someone who is already an active member of the ' +
+        'organization: this invites nobody and creates no account. Or a team by `teamId` (from ' +
+        `${prefix}list_teams), which puts every member of the team on the project with that role. ` +
+        'Exactly one of `userId`, `email` or `teamId`. Returns the new project member, a person or a ' +
+        'team entry.',
+      inputSchema: {
+        workspace: workspaceInput,
+        projectId: projectIdInput,
+        userId: userIdInput.optional(),
+        email: z.email().optional().describe('The email address the person joined the organization with.'),
+        teamId: teamIdInput.optional(),
+        role: roleInput
+      }
+    },
+    async ({ workspace, projectId, userId, email, teamId, role }) => {
+      if ([userId, email, teamId].filter((k) => k !== undefined).length !== 1) {
+        return deny(
+          'Name exactly one member: a person by userId or email, or a team by teamId, not several ' +
+            `and not none. The organization member list has both for everyone who has joined; ` +
+            `${prefix}list_teams has the team ids.`
+        );
+      }
+      const who = userId !== undefined ? { userId } : email !== undefined ? { email } : { teamId };
+      return run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}/members`, jsonBody({ ...who, role }))
+      );
+    }
+  );
+
+  server.registerTool(
+    `${prefix}set_project_member_role`,
+    {
+      description:
+        'Change what a project member may do — confirm with the user first. Needs the manager role ' +
+        `on the project. ${ROLE_LADDER} Raising someone to manager lets them manage the members and ` +
+        'archive the project too. Returns the member as they now are.',
+      inputSchema: {
+        workspace: workspaceInput,
+        projectId: projectIdInput,
+        userId: userIdInput,
+        role: roleInput
+      }
+    },
+    async ({ workspace, projectId, userId, role }) =>
+      run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}/members/${encodeURIComponent(userId)}`, {
+          ...jsonBody({ role }),
+          method: 'PATCH'
+        })
+      )
+  );
+
+  server.registerTool(
+    `${prefix}remove_project_member`,
+    {
+      description:
+        'Take someone off a project — confirm with the user first; their access to the project and ' +
+        'to what is linked to it stops immediately. Needs the manager role on the project (anyone ' +
+        'may remove themselves). This removes the person from THIS project only: they stay a member ' +
+        'of the organization. Returns a last snapshot of the member that was removed.',
+      inputSchema: { workspace: workspaceInput, projectId: projectIdInput, userId: userIdInput },
+      annotations: { destructiveHint: true }
+    },
+    async ({ workspace, projectId, userId }) =>
+      run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}/members/${encodeURIComponent(userId)}`, {
+          method: 'DELETE'
+        })
+      )
+  );
+
+  server.registerTool(
+    `${prefix}set_project_team_role`,
+    {
+      description:
+        'Change the role a team holds on a project — confirm with the user first. Every member of ' +
+        `the team holds this role on the project through it. Needs the manager role on the project. ` +
+        `${ROLE_LADDER} Returns the team entry as it now is.`,
+      inputSchema: {
+        workspace: workspaceInput,
+        projectId: projectIdInput,
+        teamId: teamIdInput,
+        role: roleInput
+      }
+    },
+    async ({ workspace, projectId, teamId, role }) =>
+      run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}/teams/${teamId}`, {
+          ...jsonBody({ role }),
+          method: 'PATCH'
+        })
+      )
+  );
+
+  server.registerTool(
+    `${prefix}remove_project_team`,
+    {
+      description:
+        'Take a team off a project — confirm with the user first; the access its members held ' +
+        'THROUGH the team stops immediately. Needs the manager role on the project. People who also ' +
+        'have their own entry on the project keep it, and the team itself stays in the organization. ' +
+        'Returns a last snapshot of the team entry that was removed.',
+      inputSchema: { workspace: workspaceInput, projectId: projectIdInput, teamId: teamIdInput },
+      annotations: { destructiveHint: true }
+    },
+    async ({ workspace, projectId, teamId }) =>
+      run(scopes.write, workspace, (c) =>
+        callApi(c, `/api/v1/projects/${projectId}/teams/${teamId}`, { method: 'DELETE' })
+      )
+  );
+}

package/src/mcp/server.ts

@@ -0,0 +1,174 @@
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { jsonText, mergeErrorHints, wrapToolErrors, type ErrorHints } from './errors.js';
+import { projectErrorHints, registerProjectTools } from './projects.js';
+import { registerTeamTools } from './teams.js';
+import {
+  callApi,
+  createScopeCheck,
+  forWorkspace,
+  pageQuery,
+  type McpScopes,
+  type McpToolContext
+} from './tool-kit.js';
+
+/**
+ * The bundled MCP server: tools are thin shims over the instance's own
+ * /api/v1 — called IN-PROCESS with the caller's Authorization header
+ * forwarded verbatim. MCP is just another API client: no privileged path, no
+ * MCP-only endpoints; new behavior lands in the API first. Identity comes
+ * from the verified credential, never from a tool parameter.
+ *
+ * Conventions (ported from the predecessor MCP template):
+ *  - read tools: `readOnlyHint: true` + a checkScope on the tool's read scope
+ *  - write tools: confirm-first description + the tool's write scope (+ destructiveHint
+ *    for deletes) — see the write tools of the tool's own set (its tools.ts)
+ *  - checkScope is UX only — the API's fail-closed allowlist is the
+ *    enforcement point; this just gives the model a clean, actionable error.
+ *
+ * get_me and list_files below are the chassis' original example tools (the
+ * end-to-end whoami proof + a cursor-paginated list), followed by
+ * `<toolPrefix>whoami`, the identity tool under the tool's own prefix; the product tool set
+ * (`<toolPrefix>*`) lives in the tool's app (its tools.ts).
+ */
+export type { McpToolContext } from './tool-kit.js';
+
+export interface McpServerInfo {
+  version: string;
+  instanceName: string;
+}
+
+/**
+ * What a tool plugs into the bundled MCP server: its own tool set (registered
+ * AFTER the three chassis tools, so `tools/list` keeps its order), the server
+ * instructions, the error hints of its domain codes, and the two scope names
+ * the chassis tools pre-check.
+ */
+export interface McpToolDefinition {
+  registerTools: (server: McpServer, ctx: McpToolContext) => void;
+  instructions: (info: McpServerInfo) => string;
+  errorHints: ErrorHints;
+  scopes: McpScopes;
+}
+
+/** The MCP half of the tool's identity (`ToolIdentity['mcp']`): the server's name and the tool names' prefix. */
+export type McpIdentity = ToolIdentity['mcp'];
+
+/**
+ * The ONE composition of an instance's hint table: the domain hints, then
+ * every chassis group (the projects today), then the tool's own last, so a
+ * tool may re-word a chassis code and never the reverse. A tool set that
+ * wraps its own errors reads the same composition (never a copy), so a
+ * chassis group added here reaches the tool's tools without a second edit.
+ */
+export function composeErrorHints(toolHints: ErrorHints, toolPrefix: string): ErrorHints {
+  return mergeErrorHints({ ...projectErrorHints(toolPrefix), ...toolHints });
+}
+
+export function buildMcpServer(
+  ctx: McpToolContext,
+  info: McpServerInfo,
+  tool: McpToolDefinition,
+  identity: McpIdentity
+): McpServer {
+  // `<prefix>whoami` (the contract of `toolPrefix`), registered below: the other chassis tools point at it.
+  const whoami = `${identity.toolPrefix}whoami`;
+  const checkScope = createScopeCheck(tool.scopes);
+  const hints = composeErrorHints(tool.errorHints, identity.toolPrefix);
+  const server = new McpServer(
+    { name: identity.serverName, version: info.version },
+    {
+      instructions: tool.instructions(info)
+    }
+  );
+
+  // The shared inputs (`inputs.ts`): the ones a tool's own set declares its tools with.
+  const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+
+  // ── Pattern 1: READ tool — the end-to-end whoami proof ────────────────────
+  server.registerTool(
+    'get_me',
+    {
+      description:
+        'Who is connected: the user this MCP connection acts as, with all their organizations. ' +
+        'Returns { user: { id, email, name }, workspace, role, via, scopes, workspaces }. ' +
+        `Everything done through this server happens as this user. (Alias of ${whoami}.)`,
+      inputSchema: { workspace: workspaceInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace }) => {
+      const denied = checkScope(ctx.principal, tool.scopes.read);
+      if (denied) return denied;
+      const c = forWorkspace(ctx, workspace);
+      return wrapToolErrors(async () => jsonText(await callApi(c, '/api/v1/me')), hints);
+    }
+  );
+
+  // ── Pattern 2: LIST tool with cursor pagination passed through ────────────
+  server.registerTool(
+    'list_files',
+    {
+      description:
+        "List a workspace's files, newest first. Returns { files: [{ id, sha256, sizeBytes, " +
+        'contentType, originalName, createdBy, createdAt }], nextCursor }. When nextCursor is ' +
+        'non-null, call again with cursor set to it for the next page. Download or upload happen ' +
+        'through the API, not through tools.',
+      inputSchema: {
+        workspace: workspaceInput,
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, limit, cursor }) => {
+      const denied = checkScope(ctx.principal, tool.scopes.read);
+      if (denied) return denied;
+      const c = forWorkspace(ctx, workspace);
+      return wrapToolErrors(
+        async () => jsonText(await callApi(c, pageQuery('/api/v1/files', { cursor, limit }))),
+        hints
+      );
+    }
+  );
+
+  // ── Identity under the tool's own prefix ───────────────────────────────────
+  // Registered by the chassis (it reads `/me`, nothing of a domain) so that the
+  // name every `workspace` argument and `get_me` point at always exists. Third,
+  // right before the tool's set: `tools/list` keeps its order.
+  server.registerTool(
+    whoami,
+    {
+      description:
+        'Who is connected: the user this MCP connection acts as, plus ALL their organizations ' +
+        '(workspaces) with per-entry role/default/suspended flags. Returns { user: { id, email, ' +
+        'name }, workspace, role, via, scopes, workspaces: [...], activeWorkspaceId }. The ' +
+        'credential is the USER; the organization is a PER-CALL parameter: every tool accepts an ' +
+        'optional `workspace` (an id from `workspaces[]`) — omitted, the entry flagged `default: ' +
+        'true` is used (else the oldest membership). Call this first to discover the ids.',
+      inputSchema: { workspace: workspaceInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace }) => {
+      const denied = checkScope(ctx.principal, tool.scopes.read);
+      if (denied) return denied;
+      const c = forWorkspace(ctx, workspace);
+      return wrapToolErrors(async () => jsonText(await callApi(c, '/api/v1/me')), hints);
+    }
+  );
+
+  // ── Projects: a chassis concept, so a chassis tool set ─────────────────────
+  // A project is a subgroup of a workspace with its own members and roles —
+  // the chassis owns it, and therefore owns the eleven tools over it. Registered
+  // under the tool's prefix, after whoami and before the tool's own set, so
+  // `tools/list` keeps one stable order across every instance.
+  registerProjectTools(server, ctx, identity, tool.scopes, checkScope, hints);
+  // Teams (PRDCT-2813): a chassis concept too, read-only over MCP, right after
+  // the projects they can be members of.
+  registerTeamTools(server, ctx, identity, tool.scopes, checkScope, hints);
+
+  // The product surface: the tool's own set, after the chassis tools.
+  tool.registerTools(server, ctx);
+
+  return server;
+}