feat(schemas): schema-driven slim fields on users (Phase 3b, DOT-560) (#111)

Sibling of DOT-558 (Phase 3a). Extends the schema-driven slim-fields
pattern (canonical: PR #109, PR #110) to the users domain — the one
piece Phase 3a deferred because the slim shape needed a privacy-aware
design pass.

Slim shape: identity-only — id, username, name, state, avatar_url,
web_url, bot. Seven fields. Always safe to expose for any user.
Privacy-sensitive fields (email, last_sign_in_at, is_admin,
two_factor_enabled, confirmed_at, current_sign_in_at, private_profile,
last_activity_on, theme_id, color_scheme_id, projects_limit, external)
are excluded by default; opt back in via fields:'all' or explicit pick.
A dedicated test pins the privacy guardrail so future expansions of
UserSlimShape can't accidentally leak those fields.

Phase-1 gaps closed along the way:
- src/schemas/users.ts: GitLabUserListSchema didn't exist; add it.
- src/tools/users.ts: get_users and search_users were never wrapped
  with parseGitLabResponse; wrap them now (a prerequisite for typed
  slim defaults to project from).

Wires four user-returning tools with fields + projection:
- get_current_user (already parse-wrapped, just adds fields+project)
- get_user (already parse-wrapped, just adds fields+project)
- get_users (newly parse-wrapped, per-username map slimmed element-wise)
- search_users (newly parse-wrapped, list slimmed)

Out of scope: list_events, get_project_events, upload_markdown,
download_attachment, health_check — they live in users.ts for
organizational convenience but don't return user-shaped data.

Tests:
- tests/schemas/users.test.ts: slim-schema parse, USER_SLIM_FIELDS
  allow-list invariant, projectField allow-list at runtime,
  **privacy guardrail** (USER_SLIM_FIELDS does NOT contain email /
  is_admin / two_factor_enabled / etc.), separate test that
  projectField actually drops those fields on a populated current-user
  fixture, GitLabUserListSchema parse, token-budget regression.
- tests/users.test.ts: default / fields:'all' / custom-pick handler
  tests for each of the four tools (12+ cases). get_current_user and
  get_user tests specifically verify privacy fields absent by default
  and present under fields:'all'. search_users test confirms `fields`
  is not forwarded to GitLab as a query string.

README "Field Projection" section extended to list the four user
endpoints.

Author: ichoosetoaccept

README.md

@@ -189,6 +189,7 @@ Currently applied to:
 - `list_pipelines`, `get_pipeline`
 - `list_releases`
 - `list_commits`, `get_commit`
+- `get_current_user`, `get_user`, `get_users`, `search_users`
 
 A spike measurement against `list_projects` with 5 owned projects went from **~32 KB → ~3 KB** by switching to the compact default. Because it's allow-list based, the compact output stays compact when GitLab adds new fields upstream.
 

src/schemas/users.ts

@@ -43,3 +43,35 @@ export const GitLabUserSchema = z
   .passthrough();
 
 export type GitLabUser = z.infer<typeof GitLabUserSchema>;
+
+export const GitLabUserListSchema = z.array(GitLabUserSchema);
+
+/**
+ * Slim shape (Phase 3b / DOT-560): identity-only fields safe to expose for
+ * any GitLab user. Deliberately excludes every privacy-sensitive field
+ * GitLab returns for the current user (email, last_sign_in_at, is_admin,
+ * two_factor_enabled, confirmed_at, current_sign_in_at, private_profile,
+ * last_activity_on, theme_id, color_scheme_id, projects_limit, external)
+ * and the bulky public-profile fields (bio, location, organization,
+ * job_title, work_information, pronouns, followers, following). Callers
+ * opt back in via `fields: "all"` or a custom `fields: [...]` allow-list.
+ *
+ * `bot` is included because the LLM often needs to know whether to treat
+ * the user as a service account vs. a person. Always safe to expose.
+ */
+export const UserSlimShape = {
+  id: true,
+  username: true,
+  name: true,
+  state: true,
+  avatar_url: true,
+  web_url: true,
+  bot: true,
+} as const;
+
+export const GitLabUserSlimSchema = GitLabUserSchema.pick(UserSlimShape);
+export type GitLabUserSlim = z.infer<typeof GitLabUserSlimSchema>;
+
+export const USER_SLIM_FIELDS = Object.keys(UserSlimShape) as ReadonlyArray<
+  keyof typeof UserSlimShape
+>;

src/tools/users.ts

@@ -1,22 +1,31 @@
 import type { McpServer, RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { parseGitLabResponse } from "../schemas/parse.js";
-import { GitLabUserSchema } from "../schemas/users.js";
+import { GitLabUserListSchema, GitLabUserSchema, USER_SLIM_FIELDS } from "../schemas/users.js";
 import { buildQueryString, defaultClient, resolveProjectId } from "../utils/gitlab-client.js";
 import type { Logger } from "../utils/logger.js";
+import { projectField, projectFields } from "../utils/projection.js";
+import { fieldsParam } from "../utils/schema-helpers.js";
 
 const GetUsersSchema = z.object({
   usernames: z.array(z.string()).describe("List of usernames to look up"),
+  fields: fieldsParam("user").optional(),
 });
 
 const GetUserSchema = z.object({
   user_id: z.number().describe("User ID"),
+  fields: fieldsParam("user").optional(),
 });
 
 const SearchUsersSchema = z.object({
   search: z.string().describe("Search query"),
   page: z.number().optional().describe("Page number"),
   per_page: z.number().optional().describe("Results per page"),
+  fields: fieldsParam("user").optional(),
+});
+
+const GetCurrentUserSchema = z.object({
+  fields: fieldsParam("user").optional(),
 });
 
 const ListEventsSchema = z.object({
@@ -101,9 +110,11 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
     "get_users",
     {
       title: "Get Users",
-      description: "Get GitLab user details by usernames",
+      description:
+        "Get GitLab user details by usernames. Returns a compact set of fields per user by default; pass `fields: 'all'` for the raw GitLab response or `fields: ['id', 'username', ...]` to pick your own.",
       inputSchema: {
         usernames: z.array(z.string()).describe("List of usernames to look up"),
+        fields: fieldsParam("user").optional(),
       },
       annotations: {
         readOnlyHint: true,
@@ -116,11 +127,20 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
 
       for (const username of args.usernames) {
         const query = buildQueryString({ username });
-        const users = await defaultClient.get<unknown[]>(`/users${query}`);
+        const raw = await defaultClient.get(`/users${query}`);
+        const users = parseGitLabResponse(GitLabUserListSchema, raw, "get_users", logger);
         // Always assign — null when the username didn't resolve. Omitting
         // missing keys would collapse signal: callers couldn't tell whether
         // a key wasn't asked for or actually didn't exist on GitLab.
-        results[username] = users.length > 0 ? users[0] : null;
+        if (users.length === 0) {
+          results[username] = null;
+          continue;
+        }
+        results[username] = projectField(
+          users[0] as unknown as Record<string, unknown>,
+          USER_SLIM_FIELDS,
+          args.fields,
+        );
       }
 
       return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
@@ -133,9 +153,11 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
     "get_user",
     {
       title: "Get User",
-      description: "Get details of a specific user by ID",
+      description:
+        "Get details of a specific user by ID. Returns a compact set of fields by default; pass `fields: 'all'` for the raw GitLab response or `fields: ['id', 'username', ...]` to pick your own.",
       inputSchema: {
         user_id: z.number().describe("User ID"),
+        fields: fieldsParam("user").optional(),
       },
       annotations: {
         readOnlyHint: true,
@@ -146,7 +168,12 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
       const args = GetUserSchema.parse(params);
       const raw = await defaultClient.get(`/users/${args.user_id}`);
       const user = parseGitLabResponse(GitLabUserSchema, raw, "get_user", logger);
-      return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] };
+      const projected = projectField(
+        user as unknown as Record<string, unknown>,
+        USER_SLIM_FIELDS,
+        args.fields,
+      );
+      return { content: [{ type: "text", text: JSON.stringify(projected, null, 2) }] };
     },
   );
   toolRef2.disable();
@@ -156,11 +183,13 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
     "search_users",
     {
       title: "Search Users",
-      description: "Search for GitLab users",
+      description:
+        "Search for GitLab users. Returns a compact set of fields per user by default; pass `fields: 'all'` for the raw GitLab response or `fields: ['id', 'username', ...]` to pick your own.",
       inputSchema: {
         search: z.string().describe("Search query"),
         page: z.number().optional().describe("Page number"),
         per_page: z.number().optional().describe("Results per page"),
+        fields: fieldsParam("user").optional(),
       },
       annotations: {
         readOnlyHint: true,
@@ -169,10 +198,18 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
     },
     async (params) => {
       const args = SearchUsersSchema.parse(params);
-      const query = buildQueryString(args);
+      const { fields, ...queryParams } = args;
+      const query = buildQueryString(queryParams);
 
-      const users = await defaultClient.get(`/users${query}`);
-      return { content: [{ type: "text", text: JSON.stringify(users, null, 2) }] };
+      const raw = await defaultClient.get(`/users${query}`);
+      const users = parseGitLabResponse(
+        GitLabUserListSchema,
+        raw,
+        "search_users",
+        logger,
+      ) as unknown as Record<string, unknown>[];
+      const projected = projectFields(users, USER_SLIM_FIELDS, fields);
+      return { content: [{ type: "text", text: JSON.stringify(projected, null, 2) }] };
     },
   );
   toolRef3.disable();
@@ -366,17 +403,25 @@ export function registerUserTools(server: McpServer, logger: Logger): Map<string
     {
       title: "Get Current User",
       description:
-        "Get details of the authenticated user (whoami). Returns the user identified by the configured PAT / OAuth token.",
-      inputSchema: {},
+        "Get details of the authenticated user (whoami). Returns the user identified by the configured PAT / OAuth token. Returns a compact set of identity fields by default; pass `fields: 'all'` for the raw GitLab response (including email, last_sign_in_at, is_admin, etc.) or `fields: ['id', 'username', 'email']` to pick your own.",
+      inputSchema: {
+        fields: fieldsParam("user").optional(),
+      },
       annotations: {
         readOnlyHint: true,
         openWorldHint: true,
       },
     },
-    async () => {
+    async (params) => {
+      const args = GetCurrentUserSchema.parse(params);
       const raw = await defaultClient.get(`/user`);
       const user = parseGitLabResponse(GitLabUserSchema, raw, "get_current_user", logger);
-      return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] };
+      const projected = projectField(
+        user as unknown as Record<string, unknown>,
+        USER_SLIM_FIELDS,
+        args.fields,
+      );
+      return { content: [{ type: "text", text: JSON.stringify(projected, null, 2) }] };
     },
   );
   toolRef8.disable();

tests/schemas/users.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "bun:test";
-import { GitLabUserSchema } from "../../src/schemas/users.js";
+import {
+  GitLabUserListSchema,
+  GitLabUserSchema,
+  GitLabUserSlimSchema,
+  USER_SLIM_FIELDS,
+  UserSlimShape,
+} from "../../src/schemas/users.js";
+import { projectField } from "../../src/utils/projection.js";
 import getCurrentUserFixture from "../fixtures/users/get_current_user.json";
 import getUserFixture from "../fixtures/users/get_user.json";
 
@@ -28,3 +35,101 @@ describe("GitLabUserSchema", () => {
     expect(result.success).toBe(false);
   });
 });
+
+describe("GitLabUserSlimSchema (Phase 3b / DOT-560)", () => {
+  it("parses the get_user fixture and types every slim field", () => {
+    const result = GitLabUserSlimSchema.safeParse(getUserFixture);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      for (const k of Object.keys(UserSlimShape)) {
+        if (k in (getUserFixture as Record<string, unknown>)) {
+          expect(k in result.data).toBe(true);
+        }
+      }
+    }
+  });
+
+  it("USER_SLIM_FIELDS exactly mirrors UserSlimShape keys", () => {
+    expect([...USER_SLIM_FIELDS].sort()).toEqual(Object.keys(UserSlimShape).sort());
+  });
+
+  it("projectField with USER_SLIM_FIELDS keeps only slim keys at runtime", () => {
+    // Use get_current_user fixture (has the admin/2FA fields populated)
+    const slim = projectField(
+      getCurrentUserFixture as Record<string, unknown>,
+      USER_SLIM_FIELDS,
+      undefined,
+    );
+    const allowed = new Set<string>(USER_SLIM_FIELDS);
+    for (const k of Object.keys(slim)) {
+      expect(allowed.has(k)).toBe(true);
+    }
+  });
+
+  it("USER_SLIM_FIELDS does NOT include privacy-sensitive fields (guardrail)", () => {
+    // Pin the privacy invariant. If a future change adds any of these to
+    // UserSlimShape, this test fails loudly and forces a deliberate decision.
+    const privacyFields = [
+      "email",
+      "public_email",
+      "last_sign_in_at",
+      "confirmed_at",
+      "last_activity_on",
+      "two_factor_enabled",
+      "current_sign_in_at",
+      "external",
+      "private_profile",
+      "is_admin",
+      "theme_id",
+      "color_scheme_id",
+      "projects_limit",
+    ];
+    const slimSet = new Set<string>(USER_SLIM_FIELDS);
+    for (const field of privacyFields) {
+      expect(slimSet.has(field)).toBe(false);
+    }
+  });
+
+  it("projectField on the current-user fixture drops every privacy-sensitive field", () => {
+    const slim = projectField(
+      getCurrentUserFixture as Record<string, unknown>,
+      USER_SLIM_FIELDS,
+      undefined,
+    ) as Record<string, unknown>;
+    for (const field of [
+      "email",
+      "last_sign_in_at",
+      "confirmed_at",
+      "last_activity_on",
+      "two_factor_enabled",
+      "current_sign_in_at",
+      "external",
+      "private_profile",
+      "is_admin",
+      "theme_id",
+      "color_scheme_id",
+      "projects_limit",
+    ]) {
+      expect(slim[field]).toBeUndefined();
+    }
+  });
+
+  it("parses an array of users via GitLabUserListSchema", () => {
+    const result = GitLabUserListSchema.safeParse([getUserFixture, getCurrentUserFixture]);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toHaveLength(2);
+    }
+  });
+
+  it("token budget: projected user is materially smaller than the full payload", () => {
+    const fullBytes = Buffer.byteLength(JSON.stringify(getCurrentUserFixture), "utf8");
+    const slim = projectField(
+      getCurrentUserFixture as Record<string, unknown>,
+      USER_SLIM_FIELDS,
+      undefined,
+    );
+    const slimBytes = Buffer.byteLength(JSON.stringify(slim), "utf8");
+    expect(slimBytes).toBeLessThanOrEqual(Math.floor(fullBytes * 0.8));
+  });
+});