abhigyanpatwari/GitNexus · error

Configured MCP repository policy must be validated before se

Error message

Configured MCP repository policy must be validated before server creation.

What it means

createMCPServer throws this when no validated McpRepositoryPolicy was passed in options while an unvalidated repository policy is present in configuration (mcpRepositoryPolicyConfigured() returns true). The library refuses to create an MCP server against a backend whose repository access policy was never parsed and validated by McpRepositoryPolicy, because an unvalidated policy could grant unintended repo access. It is a fail-closed safety check.

Source

Thrown at gitnexus/src/mcp/server.ts:105

    case 'overview':
      return `\n\n---\n**Next:** To drill into an area, READ gitnexus://repo/${repoPath}/cluster/{name}. To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;

    default:
      return '';
  }
}

/**
 * Create a configured MCP Server with all handlers registered.
 * Transport-agnostic — caller connects the desired transport.
 */
export function createMCPServer(
  backend: LocalBackend,
  options: { repositoryPolicy?: McpRepositoryPolicy } = {},
): Server {
  const readOnly = resolveMcpReadOnlyMode();
  if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
    throw new Error('Configured MCP repository policy must be validated before server creation.');
  }
  const repositoryPolicy = options.repositoryPolicy ?? McpRepositoryPolicy.unrestricted();
  const scopedBackend = repositoryPolicy.scopeBackend(backend);
  const server = new Server(
    {
      name: 'gitnexus',
      version: packageVersion(),
    },
    {
      capabilities: {
        tools: {},
        resources: {},
        prompts: {},
      },
    },
  );

  // Handle list resources request

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Parse the configured policy with McpRepositoryPolicy (e.g. McpRepositoryPolicy.fromConfig/parse) and pass the validated instance as options.repositoryPolicy.
2. If unrestricted access is truly intended, explicitly pass McpRepositoryPolicy.unrestricted() so intent is explicit.
3. Remove or disable the configured repository policy if the server should not be policy-scoped.
4. Check mcpRepositoryPolicyConfigured() before calling createMCPServer and branch to the validating code path.

Example fix

// before
const server = createMCPServer(backend);
// after
const policy = McpRepositoryPolicy.parse(config.mcpRepositoryPolicy);
const server = createMCPServer(backend, { repositoryPolicy: policy });

import { mcpRepositoryPolicyConfigured, McpRepositoryPolicy } from './mcp/policy.js';
if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
  options.repositoryPolicy = McpRepositoryPolicy.parse(loadConfiguredPolicy());
}
const server = createMCPServer(backend, options);

function hasValidatedPolicy(o: { repositoryPolicy?: McpRepositoryPolicy }): o is { repositoryPolicy: McpRepositoryPolicy } {
  return o.repositoryPolicy instanceof McpRepositoryPolicy;
}

try {
  const server = createMCPServer(backend, { repositoryPolicy: validatedPolicy });
} catch (err) {
  if ((err as Error).message.includes('repository policy must be validated')) {
    throw new Error('App bug: pass McpRepositoryPolicy.parse(config) into createMCPServer', { cause: err });
  }
  throw err;
}

When it happens

Trigger: Calling createMCPServer(backend) with no options.repositoryPolicy while config that defines an MCP repository policy exists (e.g. repositoryPolicy set in config file/env). Also passing an explicitly empty options object instead of a validated policy object.

Common situations: Server boot after adding a repository policy to config without wiring it through McpRepositoryPolicy.parse/validate before calling createMCPServer; upgrading versions where policy validation became mandatory; test harnesses constructing the server directly with only a backend.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Refusing to start the MCP HTTP server on a non-loopback host
• ${source} must be a positive integer.
• GITNEXUS_MCP_READ_ONLY must be 0 or 1.
• Insecure http:// LLM base URLs are only allowed for localhos
• ${allowedRaw.key} must not be blank.

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-09-08). Data as JSON: /api/errors/4c2451ebdee7b5b5. Report an issue: GitHub.