Merge pull request #36 from Azure/copilot/add-support-for-mcp-servers

feat: add MCP server support to apiops extract and publish

Author: EMaher

.gitignore

@@ -36,7 +36,7 @@ Desktop.ini
 .idea/
 
 # Local testing output (use --output .local-extract for local runs)
-.local-extract/
+.local-extract*/
 
 # Environment variables
 .env

package-lock.json

@@ -51,6 +51,8 @@ export const DEPENDENCY_EDGES: DependencyEdge[] = [
   { from: ResourceType.Subscription, to: ResourceType.Product, required: false },
   { from: ResourceType.Subscription, to: ResourceType.Api, required: false },
 
+  { from: ResourceType.McpServer, to: ResourceType.Api, required: true },
+
   // Tier 3 -> Tier 4 dependencies
   { from: ResourceType.ApiOperationPolicy, to: ResourceType.ApiOperation, required: true },
   { from: ResourceType.GraphQLResolverPolicy, to: ResourceType.GraphQLResolver, required: true },
@@ -91,6 +93,7 @@ export const TIER_3_RESOURCES: ResourceType[] = [
   ResourceType.ApiRelease,
   ResourceType.ApiTagDescription,
   ResourceType.ApiWiki,
+  ResourceType.McpServer,
   ResourceType.GraphQLResolver,
   ResourceType.GatewayApi,
   ResourceType.Subscription,

src/lib/dependency-graph.ts

@@ -413,6 +413,16 @@ export function isChildType(type: ResourceType): boolean {
   return firstPlaceholderIdx >= 0 && firstPlaceholderIdx < parts.length - 1;
 }
 
+/**
+ * Check if a resource type is a top-level singleton.
+ *
+ * Top-level singletons are singleton resources that are not children of
+ * another resource type (for example ServicePolicy).
+ */
+export function isTopLevelSingleton(type: ResourceType): boolean {
+  return isSingletonType(type) && !isChildType(type);
+}
+
 /**
  * Compute the publish tier for a resource type based on ARM path structure.
  * Resources are published from lowest tier to highest; same tier runs in parallel.

src/lib/resource-path.ts

@@ -1,6 +1,6 @@
 /**
  * T006: ResourceType enum and metadata
- * All 33 APIM resource types with ARM path suffixes, artifact directories, and info file names
+ * All 34 APIM resource types with ARM path suffixes, artifact directories, and info file names
  */
 
 export enum ResourceType {
@@ -37,6 +37,8 @@ export enum ResourceType {
   ProductWiki = 'ProductWiki',
   GraphQLResolver = 'GraphQLResolver',
   GraphQLResolverPolicy = 'GraphQLResolverPolicy',
+  /** MCP (Model Context Protocol) server configuration per API. Singleton per API. */
+  McpServer = 'McpServer',
 }
 
 /**
@@ -266,4 +268,12 @@ export const RESOURCE_TYPE_METADATA: Record<ResourceType, ResourceTypeMetadata>
     infoFile: 'policy.xml',
     supportsGet: true,
   },
+  [ResourceType.McpServer]: {
+    // Singleton MCP (Model Context Protocol) server configuration per API.
+    // ARM path: apis/{apiId}/mcpServers/default
+    armPathSuffix: 'apis/{0}/mcpServers/default',
+    artifactDirectory: 'apis/{0}',
+    infoFile: 'mcpServerInformation.json',
+    supportsGet: true,
+  },
 };

src/models/resource-types.ts

@@ -31,11 +31,73 @@ export interface ApiExtractionResult {
   releases: ExtractedResource[];
   tagDescriptions: ExtractedResource[];
   wiki: boolean;
+  mcpServer: boolean;
   resolvers: ExtractedResource[];
   resolverPolicies: ExtractedResource[];
   policies: string[];
 }
 
+function getApiProperties(apiJson: Record<string, unknown>): Record<string, unknown> | undefined {
+  return apiJson.properties as Record<string, unknown> | undefined;
+}
+
+function hasEmbeddedMcpConfiguration(apiJson: Record<string, unknown>): boolean {
+  const properties = getApiProperties(apiJson);
+  if (!properties) {
+    return false;
+  }
+
+  // Check if mcpTools has actual content (non-empty array), excluding null
+  const mcpTools = properties.mcpTools as unknown[] | undefined | null;
+  if (Array.isArray(mcpTools) && mcpTools.length > 0) {
+    return true;
+  }
+
+  // Check if mcpProperties exists and is not null or undefined
+  if (properties.mcpProperties != null) {
+    return true;
+  }
+
+  return false;
+}
+
+function buildEmbeddedMcpServerResource(apiJson: Record<string, unknown>): Record<string, unknown> {
+  const properties = getApiProperties(apiJson) ?? {};
+  const resourceProperties: Record<string, unknown> = {};
+
+  if (properties.mcpProperties !== undefined) {
+    resourceProperties.mcpProperties = properties.mcpProperties;
+  }
+  if (properties.mcpTools !== undefined) {
+    resourceProperties.mcpTools = properties.mcpTools;
+  }
+
+  return {
+    name: 'default',
+    properties: resourceProperties,
+  };
+
+}
+
+function hasMeaningfulMcpContent(mcpJson: Record<string, unknown>): boolean {
+  const properties = mcpJson.properties as Record<string, unknown> | undefined;
+  if (!properties) {
+    return false;
+  }
+
+  // Check if mcpTools has actual content (non-empty array), excluding null
+  const mcpTools = properties.mcpTools as unknown[] | undefined | null;
+  if (Array.isArray(mcpTools) && mcpTools.length > 0) {
+    return true;
+  }
+
+  // Check if mcpProperties exists and is not null or undefined
+  if (properties.mcpProperties != null) {
+    return true;
+  }
+
+  return false;
+}
 /**
  * Extract all API-specific resources for a single API.
  * This includes revisions, specifications, operations, policies, etc.
@@ -63,6 +125,7 @@ export async function extractApiResources(
     releases: [],
     tagDescriptions: [],
     wiki: false,
+    mcpServer: false,
     resolvers: [],
     resolverPolicies: [],
     policies: [],
@@ -138,6 +201,11 @@ export async function extractApiResources(
     client, store, context, apiDescriptor, outputDir
   );
 
+  // Extract MCP server configuration (singleton per API; silently skipped when not present)
+  result.mcpServer = await extractApiMcpServer(
+    client, store, context, apiDescriptor, apiJson, outputDir
+  );
+
   // Extract GraphQL resolvers and their policies
   const resolverResult = await extractGraphQLResolvers(
     client, store, context, apiDescriptor, apiJson, outputDir, filter, workspace
@@ -237,6 +305,11 @@ async function extractApiSpecification(
     return false;
   }
 
+  if (apiType?.toLowerCase() === 'mcp') {
+    logger.debug(`Skipping spec export for MCP API "${getNamePart(apiDescriptor.nameParts, 0)}" — MCP APIs use the Model Context Protocol endpoint, not OpenAPI`);
+    return false;
+  }
+
   if (apiType?.toLowerCase() === 'graphql' && hasGraphQLSchema(extractedSchemas)) {
     logger.debug(
       `Skipping spec export for synthetic GraphQL API "${getNamePart(apiDescriptor.nameParts, 0)}" — schema is captured via ApiSchema`
@@ -449,7 +522,7 @@ async function extractGraphQLResolvers(
   const policies: string[] = [];
 
   // Only extract resolvers for GraphQL APIs — use the already-fetched apiJson
-  const properties = apiJson.properties as Record<string, unknown> | undefined;
+  const properties = getApiProperties(apiJson);
   const apiType = properties?.type as string | undefined;
   if (apiType?.toLowerCase() !== 'graphql') {
     return { resolvers, resolverPolicies, policies };
@@ -492,3 +565,51 @@ async function extractGraphQLResolvers(
 
   return { resolvers, resolverPolicies, policies };
 }
+
+/**
+ * Extract MCP (Model Context Protocol) server configuration for an API.
+ * The MCP server is a singleton resource per API exposed at apis/{id}/mcpServers/default.
+ * Silently skips if the API does not have MCP enabled or the resource does not exist.
+ */
+async function extractApiMcpServer(
+  client: IApimClient,
+  store: IArtifactStore,
+  context: ApimServiceContext,
+  apiDescriptor: ResourceDescriptor,
+  apiJson: Record<string, unknown>,
+  outputDir: string
+): Promise<boolean> {
+  const apiType = (getApiProperties(apiJson)?.type as string | undefined)?.toLowerCase();
+
+  // Avoid creating MCP artifacts for non-MCP APIs unless they carry meaningful MCP metadata.
+  if (apiType !== 'mcp' && !hasEmbeddedMcpConfiguration(apiJson)) {
+    return false;
+  }
+
+  const mcpDescriptor: ResourceDescriptor = {
+    type: ResourceType.McpServer,
+    nameParts: [...apiDescriptor.nameParts],
+    workspace: apiDescriptor.workspace,
+  };
+
+  if (hasEmbeddedMcpConfiguration(apiJson)) {
+    await store.writeResource(outputDir, mcpDescriptor, buildEmbeddedMcpServerResource(apiJson));
+    logger.info(`Extracted ${buildResourceLabel(mcpDescriptor)} from API metadata`);
+    return true;
+  }
+
+  try {
+    const mcpJson = await client.getResource(context, mcpDescriptor);
+    if (!mcpJson || !hasMeaningfulMcpContent(mcpJson)) {
+      return false;
+    }
+
+    await store.writeResource(outputDir, mcpDescriptor, mcpJson);
+    logger.info(`Extracted ${buildResourceLabel(mcpDescriptor)}`);
+    return true;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.debug(`No MCP server configuration ${buildResourceLabel(mcpDescriptor)}: ${errorMessage}`);
+    return false;
+  }
+}

src/services/api-extractor.ts

@@ -30,6 +30,7 @@ const API_CHILD_TYPES: ResourceType[] = [
   ResourceType.ApiRelease,
   ResourceType.ApiTagDescription,
   ResourceType.ApiWiki,
+  ResourceType.McpServer,
   ResourceType.GraphQLResolver,
   ResourceType.GraphQLResolverPolicy,
 ];

src/services/api-publisher.ts

@@ -261,6 +261,7 @@ async function extractApiSubResources(
         apiResult.releases.filter((r) => r.status === 'success').length +
         apiResult.tagDescriptions.filter((r) => r.status === 'success').length +
         (apiResult.wiki ? 1 : 0) +
+        (apiResult.mcpServer ? 1 : 0) +
         apiResult.resolvers.filter((r) => r.status === 'success').length +
         apiResult.resolverPolicies.filter((r) => r.status === 'success').length;
 

src/services/extract-service.ts

@@ -15,7 +15,7 @@ import { logger } from '../lib/logger.js';
 import { isAutoGeneratedId } from '../lib/auto-generated.js';
 import { EXIT_SUCCESS, EXIT_PARTIAL, EXIT_FATAL } from '../lib/exit-codes.js';
 import { buildResourceLabel } from '../lib/resource-uri.js';
-import { getNamePart, isChildType } from '../lib/resource-path.js';
+import { getNamePart, isChildType, isTopLevelSingleton } from '../lib/resource-path.js';
 
 // Import from other agents' files (will be created in parallel)
 import { publishResource, ResourcePublishResult } from './resource-publisher.js';
@@ -188,6 +188,12 @@ async function executePuts(
   // so we exclude those children from tiers 3/4 to avoid double-publishing.
   const parentNamesByType = new Map<ResourceType, Set<string>>();
   for (const d of tierGroups.get(2) || []) {
+    // Top-level singletons such as ServicePolicy do not participate in
+    // parent-name child filtering.
+    if (isTopLevelSingleton(d.type)) {
+      continue;
+    }
+
     // Top-level types are those that are NOT child types
     if (!isChildType(d.type)) {
       if (!parentNamesByType.has(d.type)) {

src/services/publish-service.ts

@@ -15,13 +15,13 @@ import { ResourceType } from '../../../src/models/resource-types.js';
 
 describe('dependency-graph', () => {
   describe('tier constants', () => {
-    it('should have 33 total resources across all tiers', () => {
+    it('should have 34 total resources across all tiers', () => {
       const total =
         TIER_1_RESOURCES.length +
         TIER_2_RESOURCES.length +
         TIER_3_RESOURCES.length +
         TIER_4_RESOURCES.length;
-      expect(total).toBe(33);
+      expect(total).toBe(34);
     });
 
     it('should not have duplicate resources across tiers', () => {
@@ -62,9 +62,9 @@ describe('dependency-graph', () => {
   });
 
   describe('getTopologicalOrder', () => {
-    it('should return all 33 resource types', () => {
+    it('should return all 34 resource types', () => {
       const order = getTopologicalOrder();
-      expect(order).toHaveLength(33);
+      expect(order).toHaveLength(34);
     });
 
     it('should return tier-1 resources before tier-2', () => {