Merge pull request #550 from objectstack-ai/copilot/define-mcp-protocols

Author: hotlong

packages/spec/PROTOCOL_MAP.md

@@ -75,6 +75,7 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | :--- | :--- | :--- |
 | [`agent.zod.ts`](src/ai/agent.zod.ts) | ⭐ | **AI Agent**. Attributes of an AI assistant (role, personality, model). |
 | [`agent-action.zod.ts`](src/ai/agent-action.zod.ts) | ⭐ | **Tools & Actions**. Capabilities exposed to the AI (Function Calling). |
+| [`mcp.zod.ts`](src/ai/mcp.zod.ts) | ⭐ | **Model Context Protocol (MCP)**. Standard protocol for connecting AI to tools, resources, and data sources. |
 | [`rag-pipeline.zod.ts`](src/ai/rag-pipeline.zod.ts) | ⭐ | **RAG**. Retrieval Augmented Generation configurations. |
 | [`model-registry.zod.ts`](src/ai/model-registry.zod.ts) | | **LLM Registry**. Configuration for model providers (OpenAI, Anthropic). |
 | [`conversation.zod.ts`](src/ai/conversation.zod.ts) | | **Chat Session**. History and context management for AI chats. |

packages/spec/README.md

@@ -8,7 +8,7 @@ The **Source of Truth** for the ObjectStack Protocol. Contains strictly typed Zo
 - **Data**: Objects, Fields, Validation Rules.
 - **UI**: Views, Layouts, Dashboards.
 - **Automation**: Flows, Workflows, Triggers.
-- **AI**: Agents, RAG Pipelines, Models.
+- **AI**: Agents, RAG Pipelines, Models, MCP Servers.
 
 ## Usage
 
@@ -58,3 +58,133 @@ if (result.success) {
   console.log('Valid object:', result.data);
 }
 ```
+
+## MCP (Model Context Protocol) Integration
+
+Define MCP servers to connect AI agents to your ObjectStack data and tools:
+
+```typescript
+import { MCPServerConfigSchema } from '@objectstack/spec/ai';
+
+// Define an MCP server exposing ObjectStack data
+export const objectStackMCP = MCPServerConfigSchema.parse({
+  name: 'objectstack_mcp',
+  label: 'ObjectStack MCP Server',
+  description: 'Connects AI agents to ObjectStack data and workflows',
+  
+  serverInfo: {
+    name: 'ObjectStack MCP',
+    version: '1.0.0',
+    capabilities: {
+      resources: true,
+      resourceTemplates: true,
+      tools: true,
+      prompts: true,
+    },
+  },
+  
+  transport: {
+    type: 'http',
+    url: 'https://api.objectstack.ai/mcp',
+    auth: {
+      type: 'bearer',
+      secretRef: 'system:mcp_api_key',
+    },
+  },
+  
+  // Expose data as resources
+  resourceTemplates: [
+    {
+      uriPattern: 'objectstack://objects/{objectName}',
+      name: 'Object Data',
+      description: 'Access object records',
+      parameters: [
+        {
+          name: 'objectName',
+          type: 'string',
+          required: true,
+          description: 'Name of the object to access',
+        },
+      ],
+      handler: 'resources.getObjectData',
+    },
+  ],
+  
+  // Expose workflows as tools
+  tools: [
+    {
+      name: 'create_record',
+      description: 'Create a new record in any object',
+      parameters: [
+        {
+          name: 'object',
+          type: 'string',
+          description: 'Object name (e.g., "account", "contact")',
+          required: true,
+        },
+        {
+          name: 'data',
+          type: 'object',
+          description: 'Record data as key-value pairs',
+          required: true,
+        },
+      ],
+      handler: 'flows.create_record',
+      sideEffects: 'write',
+      requiresConfirmation: true,
+    },
+    {
+      name: 'search_records',
+      description: 'Search for records using natural language or filters',
+      parameters: [
+        {
+          name: 'object',
+          type: 'string',
+          description: 'Object to search in',
+          required: true,
+        },
+        {
+          name: 'query',
+          type: 'string',
+          description: 'Search query',
+          required: true,
+        },
+      ],
+      handler: 'data.search',
+      sideEffects: 'read',
+    },
+  ],
+  
+  // Provide prompt templates
+  prompts: [
+    {
+      name: 'analyze_customer_data',
+      description: 'Analyze customer data and generate insights',
+      messages: [
+        {
+          role: 'system',
+          content: 'You are a data analyst specializing in customer insights.',
+        },
+        {
+          role: 'user',
+          content: 'Analyze the following customer data and provide insights: {{customer_data}}',
+        },
+      ],
+      arguments: [
+        {
+          name: 'customer_data',
+          type: 'string',
+          required: true,
+          description: 'Customer data in JSON format',
+        },
+      ],
+    },
+  ],
+  
+  autoStart: true,
+  healthCheck: {
+    enabled: true,
+    interval: 60000,
+  },
+});
+```