fix: anonymous client

[imbenrabi]

No description provided.

[Copilot]

Pull request overview

This PR removes the “anonymous client” fallback for MCP protocol endpoints by requiring a valid mcp-client-id header, while also refactoring several modules toward a builder-based construction style and consolidating scattered helpers/types into *.utils.ts / *.types.ts files.

Changes:

• Enforce mcp-client-id validation (reject missing/blank with 400) and update tests/docs accordingly.
• Refactor server/transport/core/session/permissions components to use builder patterns and centralize shared utilities/types.
• Move permission/session validation + bundle helpers into new permissions.utils.ts / session.utils.ts and add new *.types.ts modules.

Reviewed changes

Copilot reviewed 44 out of 44 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/validateSessionContextConfig.test.ts	Updates import path for session config validation helper.
tests/validatePermissionConfig.test.ts	Updates import path for permission config validation helper.
tests/permissionAwareFastifyTransport.test.ts	Adds/updates tests asserting POST /mcp rejects missing/blank mcp-client-id.
tests/fastifyTransport.test.ts	Adds tests asserting POST /mcp rejects missing/blank mcp-client-id.
tests/customEndpoints.test.ts	Switches imports to consolidated HTTP utils module.
tests/createPermissionAwareBundle.test.ts	Updates imports after permissions utils/types split.
tests/createMcpServer.test.ts	Updates transport mock to support new builder-based wiring.
src/types/index.ts	Redirects CreateMcpServerOptions type import to server.types.ts.
src/types/AGENTS.md	Updates maintenance reference to root AGENTS.md.
src/session/session.utils.ts	Retains session config validation; trims doc verbosity.
src/session/session.types.ts	Introduces shared session/cache types (e.g., SessionContextResult, cache options).
src/session/SessionContextResolver.ts	Moves SessionContextResult to types file; adds builder; refactors resolve flow into helpers.
src/session/ClientResourceCache.ts	Moves option/entry types to session.types.ts; adds builder.
src/session/AGENTS.md	Updates maintenance reference to root AGENTS.md.
src/server/server.utils.ts	Adds shared utilities: startup config schema/validation, notifier adapter, meta-tools flag resolver.
src/server/server.types.ts	Adds shared public server types (CreateMcpServerOptions, McpServerHandle).
src/server/createPermissionBasedMcpServer.ts	Refactors into helper functions; switches to consolidated permissions/session utils; uses builder-style orchestrator/transport creation.
src/server/createMcpServer.ts	Extracts types to server.types.ts; moves shared utils to server.utils.ts; uses builder-based transport/orchestrator wiring.
src/server/AGENTS.md	Documents new helper-based flow and builder/optional-field invariant.
src/permissions/validatePermissionConfig.ts	Removed; logic moved into permissions.utils.ts.
src/permissions/permissions.utils.ts	New consolidated permissions module: validation, bundle factory, exposure policy sanitization.
src/permissions/permissions.types.ts	New shared permission transport/bundle/context types.
src/permissions/createPermissionAwareBundle.ts	Removed; logic moved into permissions.utils.ts.
src/permissions/PermissionResolver.ts	Adds builder; trims doc verbosity.
src/permissions/PermissionAwareFastifyTransport.ts	Requires mcp-client-id for POST /mcp; caches by clientId; introduces builder; refactors imports to new http/permissions types/utils.
src/permissions/AGENTS.md	Updates invariants/docs to reflect required mcp-client-id behavior and caching changes.
src/mode/mode.types.ts	New shared mode-related types/constants extracted from resolvers.
src/mode/ModuleResolver.ts	Uses extracted mode types/constants; adds builder; refactors resolution into helper methods.
src/mode/ModeResolver.ts	Uses extracted mode types; adds builder; extracts repeated validation error formatting.
src/mode/AGENTS.md	Updates maintenance reference to root AGENTS.md.
src/index.ts	Updates public type exports to use server.types.ts and session.types.ts; updates HTTP exports to http.utils.ts/http.types.ts.
src/http/http.utils.ts	Consolidates endpoint definition/registration helpers; exports createValidationError.
src/http/http.types.ts	Extracts transport/options/bundle callback and endpoint types into a shared types module.
src/http/FastifyTransport.ts	Requires mcp-client-id for POST /mcp; adds builder; refactors route registration into named methods.
src/http/AGENTS.md	Updates invariant: /mcp endpoints require mcp-client-id; custom endpoints still allow anonymous IDs.
src/core/core.types.ts	New shared core option types extracted from classes.
src/core/ToolRegistry.ts	Moves options type to core.types.ts; adds builder.
src/core/ServerOrchestrator.ts	Switches to builder usage for dependencies; adds builder; refactors startup resolution helpers.
src/core/DynamicToolManager.ts	Moves options type to core.types.ts; adds builder; refactors tool enabling into helpers.
src/core/AGENTS.md	Updates maintenance reference to root AGENTS.md.
package.json	Version bump 0.6.1 → 0.6.2.
README.md	Updates client-id behavior documentation (400 on missing for /mcp endpoints).
CLAUDE.md	Updates to point contributors/agents to root AGENTS.md intent layer.
AGENTS.md	Replaces prior agent usage doc with intent-layer root, invariants, and style rules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

src/http/FastifyTransport.ts:274

• req.headers["mcp-client-id"] can be string | string[] | undefined in Fastify. Casting to string and calling .trim() can throw at runtime when the header is provided multiple times (array). Normalize first (e.g., handle Array.isArray(value) / typeof value === "string") before trimming.

      const clientIdHeader = (
        req.headers["mcp-client-id"] as string | undefined
      )?.trim();

src/permissions/PermissionAwareFastifyTransport.ts:440

• #extractClientContext() assumes req.headers["mcp-client-id"] is a string and calls .trim(). In Fastify it may be string[], which would throw at runtime (notably for custom endpoints where you still allow anonymous IDs). Consider normalizing string | string[] | undefined before trimming.

    const clientIdHeader = (
      req.headers["mcp-client-id"] as string | undefined
    )?.trim();
    const clientId =
      clientIdHeader && clientIdHeader.length > 0
        ? clientIdHeader
        : `anon-${randomUUID()}`;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.