Add Model Context Protocol (MCP) specification for AI agent integration by Copilot · Pull Request #550 · objectstack-ai/framework

Copilot · 2026-02-08T09:35:58Z

Adds standardized protocol for connecting AI agents to ObjectStack data, workflows, and tools via MCP.

Schema Implementation

17 Zod schemas in src/ai/mcp.zod.ts:

Transport layer: stdio, HTTP, WebSocket, gRPC with auth and retry configuration
Resource protocol: Static resources + dynamic URI templates (objectstack://objects/{name})
Tool protocol: Function calling with recursive parameter schemas, side effect declarations, confirmation flows
Prompt protocol: Reusable templates with variable substitution
Server/Client configs: Health checks, rate limiting, access control

Key design decision: Tool parameters use explicit type-first pattern to handle recursive structures:

export type MCPToolParameter = {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  properties?: Record<string, MCPToolParameter>;  // Recursive
  items?: MCPToolParameter;
};

export const MCPToolParameterSchema: z.ZodType<MCPToolParameter> = z.object({
  // ... definition using z.lazy() for recursion
});

This avoids TypeScript circular reference errors in dts generation while maintaining full type inference.

Usage Example

import { MCPServerConfigSchema } from '@objectstack/spec/ai';

export const objectStackMCP = MCPServerConfigSchema.parse({
  name: 'objectstack_mcp',
  transport: { type: 'http', url: 'https://api.example.com/mcp' },
  
  resourceTemplates: [{
    uriPattern: 'objectstack://objects/{objectName}/{recordId}',
    handler: 'resources.getRecord',
  }],
  
  tools: [{
    name: 'create_record',
    parameters: [
      { name: 'object', type: 'string', required: true },
      { name: 'data', type: 'object', required: true },
    ],
    handler: 'flows.create_record',
    sideEffects: 'write',
    requiresConfirmation: true,
  }],
});

Documentation

English guide: docs/MCP_GUIDE.md - Architecture, use cases, integration patterns
Chinese guide: docs/MCP_GUIDE_CN.md - Complete implementation examples for ObjectStack workflows
Protocol map: Updated AI section to include MCP alongside Agent and RAG protocols

Testing

27 test cases covering transport configs, resource templates, tool definitions, prompts, and server configurations.

Original prompt

在我整个协议框架中，如何和大模型对接，定义mcp相关的协议，并更新相关文档。

The user has attached the following file paths as relevant context:

.github/copilot-instructions.md

Created from VS Code.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

vercel · 2026-02-08T09:36:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-studio	Error		Feb 8, 2026 10:23am
spec	Ready	Preview, Comment	Feb 8, 2026 10:23am

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot

Pull request overview

Adds a new AI-facing Model Context Protocol (MCP) specification to @objectstack/spec, enabling standardized configuration of transports, resources, tools, prompts, and server/client settings for agent integrations. Also updates exports, docs, and regenerates JSON Schemas to reflect the new AI schemas and existing service/route schema updates.

Changes:

Add MCP Zod schemas + Vitest coverage (src/ai/mcp.zod.ts, src/ai/mcp.test.ts) and export them from src/ai/index.ts.
Add MCP documentation and map entry updates (docs/MCP_GUIDE.md, README.md, PROTOCOL_MAP.md).
Regenerate JSON Schema outputs (new json-schema/ai/* MCP schemas + refreshed service/discovery/manifest-related schemas).

Reviewed changes

Copilot reviewed 52 out of 52 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/spec/src/ai/mcp.zod.ts	Defines MCP transport/resource/tool/prompt/server/client schemas and TS type exports.
packages/spec/src/ai/mcp.test.ts	Adds Vitest coverage for MCP schema parsing.
packages/spec/src/ai/index.ts	Exports MCP schemas from the AI barrel file.
packages/spec/docs/MCP_GUIDE.md	Adds an MCP integration guide and examples.
packages/spec/README.md	Documents MCP usage at the package level with examples.
packages/spec/PROTOCOL_MAP.md	Registers MCP in the protocol map under AI.
packages/spec/json-schema/system/ServiceStatus.json	Regenerated JSON schema (service enum expansion).
packages/spec/json-schema/system/ServiceConfig.json	Regenerated JSON schema (service enum expansion).
packages/spec/json-schema/system/KernelServiceMap.json	Regenerated JSON schema (service enum expansion).
packages/spec/json-schema/system/CoreServiceName.json	Regenerated JSON schema (service enum expansion).
packages/spec/json-schema/kernel/Manifest.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/ListPackagesResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/InstalledPackage.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/InstallPackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/InstallPackageRequest.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/GetPackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/EnablePackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/kernel/DisablePackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/hub/ComposerResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/ListPackagesResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/InstallPackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/InstallPackageRequest.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/GetPackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/GetDiscoveryResponse.json	Regenerated JSON schema (API routes/capabilities updates).
packages/spec/json-schema/api/EnablePackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/DisablePackageResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/CompileManifestResponse.json	Regenerated JSON schema (includes `contributes.routes`).
packages/spec/json-schema/api/ApiRoutes.json	Regenerated JSON schema (route description updates + extra routes).
packages/spec/json-schema/api/ApiCapabilities.json	Regenerated JSON schema (capability expansion).
packages/spec/json-schema/api/Discovery.json	Regenerated JSON schema (route description updates + capability expansion).
packages/spec/json-schema/api/DispatcherRoute.json	New generated JSON schema for dispatcher route shape.
packages/spec/json-schema/api/DispatcherConfig.json	New generated JSON schema for dispatcher config shape.
packages/spec/json-schema/ai/MCPTransportType.json	New generated JSON schema for MCP transport type.
packages/spec/json-schema/ai/MCPTransportConfig.json	New generated JSON schema for MCP transport config.
packages/spec/json-schema/ai/MCPResourceType.json	New generated JSON schema for MCP resource type.
packages/spec/json-schema/ai/MCPResource.json	New generated JSON schema for MCP resource.
packages/spec/json-schema/ai/MCPResourceTemplate.json	New generated JSON schema for MCP resource templates.
packages/spec/json-schema/ai/MCPToolParameter.json	New generated JSON schema for MCP tool parameters.
packages/spec/json-schema/ai/MCPTool.json	New generated JSON schema for MCP tool definitions.
packages/spec/json-schema/ai/MCPCapability.json	New generated JSON schema for MCP capability flags.
packages/spec/json-schema/ai/MCPServerInfo.json	New generated JSON schema for MCP server info.
packages/spec/json-schema/ai/MCPServerConfig.json	New generated JSON schema for MCP server config.
packages/spec/json-schema/ai/MCPResourceRequest.json	New generated JSON schema for MCP resource request.
packages/spec/json-schema/ai/MCPResourceResponse.json	New generated JSON schema for MCP resource response.
packages/spec/json-schema/ai/MCPToolCallRequest.json	New generated JSON schema for MCP tool call request.
packages/spec/json-schema/ai/MCPToolCallResponse.json	New generated JSON schema for MCP tool call response.
packages/spec/json-schema/ai/MCPPromptArgument.json	New generated JSON schema for MCP prompt arguments.
packages/spec/json-schema/ai/MCPPromptMessage.json	New generated JSON schema for MCP prompt messages.
packages/spec/json-schema/ai/MCPPrompt.json	New generated JSON schema for MCP prompt templates.
packages/spec/json-schema/ai/MCPPromptRequest.json	New generated JSON schema for MCP prompt request.
packages/spec/json-schema/ai/MCPPromptResponse.json	New generated JSON schema for MCP prompt response.
packages/spec/json-schema/ai/MCPClientConfig.json	New generated JSON schema for MCP client config.

Copilot · 2026-02-08T10:23:13Z

+## MCP (Model Context Protocol) Integration
+
+Define MCP servers to connect AI agents to your ObjectStack data and tools:
+


PR description mentions adding a Chinese MCP guide (docs/MCP_GUIDE_CN.md), but only docs/MCP_GUIDE.md exists in this PR. Either add the CN doc as described or update the PR description to match what’s actually included.

Copilot · 2026-02-08T10:23:14Z

+export const MCPTransportConfigSchema = z.object({
+  type: MCPTransportTypeSchema,
+
+  /** HTTP/WebSocket Configuration */
+  url: z.string().url().optional().describe('Server URL (for HTTP/WebSocket/gRPC)'),
+  headers: z.record(z.string(), z.string()).optional().describe('Custom headers for requests'),


MCPTransportConfigSchema currently allows invalid combinations (e.g., { type: 'http' } with no url, or { type: 'stdio' } with no command). Consider modeling this as a discriminated union (by type) or adding a superRefine so url is required for http|websocket|grpc and command is required for stdio (and optionally forbid irrelevant fields per transport).

Copilot · 2026-02-08T10:23:14Z

+  auth: z.object({
+    type: z.enum(['none', 'bearer', 'api_key', 'oauth2', 'custom']).default('none'),
+    token: z.string().optional().describe('Bearer token or API key'),
+    secretRef: z.string().optional().describe('Reference to stored secret'),
+    headerName: z.string().optional().describe('Custom auth header name'),
+  }).optional(),


The auth block doesn't validate that credentials are present when auth.type is bearer/api_key/oauth2/custom (both token and secretRef are optional). This makes it easy to produce a config that passes schema validation but cannot authenticate at runtime; add a refinement to require either token or secretRef (and optionally enforce headerName when type: 'custom').

Copilot · 2026-02-08T10:23:14Z

+/**
+ * MCP Tool Parameter Type (inferred before schema to avoid circular reference)
+ */
+export type MCPToolParameter = {
+  name: string;


The comment says the MCPToolParameter type is defined before the schema to avoid circular references, but the type is declared after MCPToolParameterSchema. Either move the type above the schema (matching the comment and the documented approach) or update the comment so it accurately reflects the implementation.

Copilot · 2026-02-08T10:23:14Z

+export const MCPResourceResponseSchema = z.object({
+  resource: MCPResourceSchema,
+  content: z.unknown().describe('Resource content'),
+});


MCPResourceResponseSchema makes content required, but the generated JSON Schema (json-schema/ai/MCPResourceResponse.json) does not list content as required (likely due to how z.unknown() is rendered). If content is truly required for consumers/IDE validation, consider using a JSON-schema-representable union (or another approach) so JSON schema generation can enforce it; otherwise make content optional to keep runtime and generated schema consistent.

Copilot · 2026-02-08T10:23:14Z

+export type MCPTransportType = z.infer<typeof MCPTransportTypeSchema>;
+export type MCPTransportConfig = z.infer<typeof MCPTransportConfigSchema>;
+export type MCPResourceType = z.infer<typeof MCPResourceTypeSchema>;
+export type MCPResource = z.infer<typeof MCPResourceSchema>;
+export type MCPResourceTemplate = z.infer<typeof MCPResourceTemplateSchema>;
+// MCPToolParameter type is exported above with the schema
+export type MCPTool = z.infer<typeof MCPToolSchema>;
+export type MCPPromptArgument = z.infer<typeof MCPPromptArgumentSchema>;
+export type MCPPromptMessage = z.infer<typeof MCPPromptMessageSchema>;
+export type MCPPrompt = z.infer<typeof MCPPromptSchema>;
+export type MCPCapability = z.infer<typeof MCPCapabilitySchema>;
+export type MCPServerInfo = z.infer<typeof MCPServerInfoSchema>;
+export type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+export type MCPResourceRequest = z.infer<typeof MCPResourceRequestSchema>;
+export type MCPResourceResponse = z.infer<typeof MCPResourceResponseSchema>;
+export type MCPToolCallRequest = z.infer<typeof MCPToolCallRequestSchema>;
+export type MCPToolCallResponse = z.infer<typeof MCPToolCallResponseSchema>;
+export type MCPPromptRequest = z.infer<typeof MCPPromptRequestSchema>;
+export type MCPPromptResponse = z.infer<typeof MCPPromptResponseSchema>;
+export type MCPClientConfig = z.infer<typeof MCPClientConfigSchema>;


The exported types at the bottom use z.infer<...> for configuration schemas that apply many .default(...) values. This typically makes properties like timeout, retryAttempts, etc. appear required in TypeScript even though they can be omitted in config input. Consider exporting parallel ...Input types using z.input<typeof ...Schema> (or switching these config types to z.input) so consumers can author configs without needing to spell out defaulted fields.

Copilot · 2026-02-08T10:23:15Z

+  it('should enforce URL for HTTP/WebSocket transport', () => {
+    const transport = {
+      type: 'http' as const,
+      url: 'https://api.example.com/mcp',
+    };
+
+    expect(() => MCPTransportConfigSchema.parse(transport)).not.toThrow();
+  });


This test is titled "should enforce URL for HTTP/WebSocket transport" but it only asserts that parsing succeeds when url is present. Add a failing case (e.g. type: 'http' without url) and/or rename the test to reflect what it actually verifies. This will also guard the transport-type conditional validation once added.

Copilot · 2026-02-08T10:23:15Z

+- [ObjectStack Agent Configuration](./agent.zod.ts)
+- [ObjectStack API Protocol](../api/protocol.zod.ts)


The reference links at the end appear to point to non-existent paths from packages/spec/docs/ (e.g. ./agent.zod.ts and ../api/protocol.zod.ts). Update these to the correct locations under ../src/... so the documentation links work in GitHub and local checkouts.

Suggested change

- [ObjectStack Agent Configuration](./agent.zod.ts)

- [ObjectStack API Protocol](../api/protocol.zod.ts)

- [ObjectStack Agent Configuration](../src/ai/agent.zod.ts)

- [ObjectStack API Protocol](../src/api/protocol.zod.ts)

Initial plan

262c677

Copilot AI assigned Copilot and hotlong Feb 8, 2026

Copilot started work on behalf of hotlong February 8, 2026 09:36 View session

vercel Bot deployed to Preview – spec February 8, 2026 09:38 View deployment

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 09:39 Failure

Add MCP (Model Context Protocol) schemas and tests

a4baee2

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 09:41 Failure

vercel Bot deployed to Preview – spec February 8, 2026 09:43 View deployment

Add comprehensive MCP documentation and fix TypeScript build

384d831

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Define MCP protocols for integration with large models~~ Add Model Context Protocol (MCP) specification for AI agent integration Feb 8, 2026

Copilot AI requested a review from hotlong February 8, 2026 09:46

Copilot finished work on behalf of hotlong February 8, 2026 09:46

vercel Bot deployed to Preview – spec February 8, 2026 09:46 View deployment

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 09:47 Failure

删除 MCP_GUIDE_CN.md

122a829

hotlong marked this pull request as ready for review February 8, 2026 10:16

Copilot AI review requested due to automatic review settings February 8, 2026 10:16

github-actions Bot added documentation Improvements or additions to documentation tests protocol:ai labels Feb 8, 2026

hotlong merged commit 330678d into main Feb 8, 2026
9 of 11 checks passed

github-actions Bot added the size/xl label Feb 8, 2026

Copilot started reviewing on behalf of hotlong February 8, 2026 10:16 View session

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 10:17 Failure

Copilot AI reviewed Feb 8, 2026

View reviewed changes

vercel Bot deployed to Preview – spec February 8, 2026 10:23 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Model Context Protocol (MCP) specification for AI agent integration#550

Add Model Context Protocol (MCP) specification for AI agent integration#550
hotlong merged 4 commits into
mainfrom
copilot/define-mcp-protocols

Copilot AI commented Feb 8, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Feb 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		## MCP (Model Context Protocol) Integration

		Define MCP servers to connect AI agents to your ObjectStack data and tools:

		- [ObjectStack Agent Configuration](./agent.zod.ts)
		- [ObjectStack API Protocol](../api/protocol.zod.ts)

Conversation

Copilot AI commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Schema Implementation

Usage Example

Documentation

Testing

Uh oh!

vercel Bot commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 8, 2026 •

edited

Loading

vercel Bot commented Feb 8, 2026 •

edited

Loading