@bluefly/openstandardagents 0.4.8 → 0.5.0

package/spec/v0.5/extensions/mcp/README.md

@@ -0,0 +1,276 @@
+# MCP (Model Context Protocol) Extension
+
+**Version**: 0.4.6
+**Status**: Stable
+**Framework**: [Anthropic MCP](https://modelcontextprotocol.io/)
+
+## Overview
+
+The MCP extension enables native integration with Anthropic's Model Context Protocol, providing standardized context sharing, resource access, and tool invocation across LLM applications.
+
+## Features
+
+- **MCP Server Connections**: Connect to stdio, HTTP, WebSocket, or SSE-based MCP servers
+- **Resource Management**: Expose and consume MCP resources (files, databases, APIs)
+- **Prompt Templates**: Define reusable prompt templates with arguments
+- **Tool Integration**: Expose tools via MCP for LLM invocation
+- **Sampling Support**: Enable agents to request LLM completions
+- **Capability Discovery**: Dynamic capability negotiation
+
+## Schema Reference
+
+### MCP Server Configuration
+
+```yaml
+extensions:
+  mcp:
+    servers:
+      - name: filesystem
+        description: "Local filesystem access"
+        transport:
+          type: stdio
+          command: npx
+          args:
+            - "-y"
+            - "@modelcontextprotocol/server-filesystem"
+            - "/path/to/allowed/files"
+        version: "0.1.0"
+        capabilities:
+          resources:
+            subscribe: true
+            listChanged: true
+```
+
+### Transport Types
+
+1. **stdio**: Local process communication
+   ```yaml
+   transport:
+     type: stdio
+     command: node
+     args: ["server.js"]
+   ```
+
+2. **HTTP/WebSocket/SSE**: Network-based transport
+   ```yaml
+   transport:
+     type: http
+     url: https://mcp-server.example.com/api
+     headers:
+       Authorization: "Bearer ${MCP_TOKEN}"
+     timeout: 30
+   ```
+
+### Resource Definition
+
+```yaml
+extensions:
+  mcp:
+    resources:
+      - uri: "file:///workspace/README.md"
+        name: "Project README"
+        description: "Main project documentation"
+        mimeType: "text/markdown"
+        annotations:
+          audience: ["user", "assistant"]
+          priority: 0.9
+        contents:
+          - type: text
+            text: "# Project Documentation..."
+            mimeType: "text/markdown"
+```
+
+### Prompt Templates
+
+```yaml
+extensions:
+  mcp:
+    prompts:
+      - name: "review-code"
+        description: "Review code changes for quality and security"
+        arguments:
+          - name: "code"
+            description: "Code to review"
+            required: true
+          - name: "language"
+            description: "Programming language"
+            required: false
+        messages:
+          - role: system
+            content: "You are a code reviewer focused on quality and security."
+          - role: user
+            content: "Review this {{language}} code:\n\n{{code}}"
+```
+
+### Tool Definition
+
+```yaml
+extensions:
+  mcp:
+    tools:
+      - name: "read_file"
+        description: "Read contents of a file"
+        inputSchema:
+          type: object
+          required: ["path"]
+          properties:
+            path:
+              type: string
+              description: "File path to read"
+```
+
+### Sampling Configuration
+
+```yaml
+extensions:
+  mcp:
+    sampling:
+      enabled: true
+      maxTokens: 4096
+      temperature: 0.7
+      stopSequences: ["</response>"]
+      modelPreferences:
+        - "claude-sonnet-4-20250514"
+        - "gpt-4o"
+    capabilities:
+      sampling:
+        enabled: true
+```
+
+## Use Cases
+
+### 1. Filesystem MCP Server
+
+```yaml
+apiVersion: ossa/v0.4.6
+kind: Agent
+metadata:
+  name: file-assistant
+  version: 1.0.0
+spec:
+  extensions:
+    mcp:
+      servers:
+        - name: filesystem
+          description: "Access project files"
+          transport:
+            type: stdio
+            command: npx
+            args:
+              - "-y"
+              - "@modelcontextprotocol/server-filesystem"
+              - "/workspace"
+          capabilities:
+            resources:
+              subscribe: true
+              listChanged: true
+```
+
+### 2. Database MCP Server
+
+```yaml
+apiVersion: ossa/v0.4.6
+kind: Agent
+metadata:
+  name: database-assistant
+  version: 1.0.0
+spec:
+  extensions:
+    mcp:
+      servers:
+        - name: postgres
+          description: "PostgreSQL database access"
+          transport:
+            type: stdio
+            command: npx
+            args:
+              - "-y"
+              - "@modelcontextprotocol/server-postgres"
+          env:
+            DATABASE_URL: "postgresql://user:${POSTGRES_PASSWORD}@localhost:5432/db"
+          capabilities:
+            tools:
+              listChanged: false
+```
+
+### 3. Custom MCP Resources
+
+```yaml
+apiVersion: ossa/v0.4.6
+kind: Agent
+metadata:
+  name: documentation-agent
+  version: 1.0.0
+spec:
+  extensions:
+    mcp:
+      resources:
+        - uri: "docs://api-reference"
+          name: "API Reference"
+          description: "Complete API documentation"
+          mimeType: "text/markdown"
+          contents:
+            - type: text
+              text: "# API Reference\n\n..."
+              mimeType: "text/markdown"
+      prompts:
+        - name: "explain-api"
+          description: "Explain an API endpoint"
+          arguments:
+            - name: "endpoint"
+              description: "API endpoint path"
+              required: true
+          messages:
+            - role: system
+              content: "You are an API documentation expert."
+            - role: user
+              content: "Explain the {{endpoint}} API endpoint"
+```
+
+## Best Practices
+
+1. **Server Naming**: Use descriptive names that indicate the server's purpose
+2. **Transport Security**: Use HTTPS/WSS for network transports and validate certificates
+3. **Resource URIs**: Follow URI scheme conventions (file://, db://, http://)
+4. **Error Handling**: Configure appropriate timeouts and retry policies
+5. **Capabilities**: Declare capabilities accurately to enable proper protocol negotiation
+6. **Environment Variables**: Use env vars for sensitive configuration (API keys, credentials)
+7. **Resource Updates**: Enable `subscribe` and `listChanged` for dynamic resources
+
+## Validation
+
+The MCP validator checks:
+
+- Server transport configuration is complete and valid
+- Resource URIs are properly formatted
+- No duplicate resource URIs or prompt/tool names
+- Content types match declared MIME types
+- Sampling configuration is consistent with capabilities
+- Network URLs are valid and accessible
+
+## Integration
+
+### With ValidationService
+
+```typescript
+import { MCPValidator } from './validators/mcp.validator.js';
+
+const mcpValidator = container.get(MCPValidator);
+const result = mcpValidator.validate(manifest);
+```
+
+### With Agent Runtime
+
+MCP servers are automatically initialized when an agent starts. Resources, prompts, and tools are registered with the MCP protocol handler.
+
+## Related Extensions
+
+- **Kagent**: Kubernetes-native deployment
+- **A2A**: Agent-to-agent communication
+- **LangChain**: LangChain integration
+
+## References
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [MCP Server Examples](https://github.com/modelcontextprotocol/servers)
+- [OSSA v0.4.6 Specification](../../README.md)

package/spec/v0.5/extensions/mcp/mcp.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.4.6/extensions/mcp.json",
+  "title": "MCP Extension Schema",
+  "description": "Model Context Protocol extension for OSSA agents",
+  "type": "object",
+  "properties": {
+    "servers": {
+      "type": "array",
+      "description": "MCP server configurations",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "command": { "type": "string" },
+          "args": { "type": "array", "items": { "type": "string" } },
+          "env": { "type": "object", "additionalProperties": { "type": "string" } },
+          "transport": {
+            "type": "string",
+            "enum": ["stdio", "sse", "websocket"],
+            "default": "stdio"
+          }
+        },
+        "required": ["name", "command"],
+        "additionalProperties": false
+      }
+    },
+    "tools": {
+      "type": "array",
+      "description": "MCP tools exposed by servers",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "inputSchema": { "type": "object" },
+          "server": { "type": "string" }
+        },
+        "required": ["name", "description", "inputSchema"],
+        "additionalProperties": false
+      }
+    },
+    "resources": {
+      "type": "array",
+      "description": "MCP resources provided by servers",
+      "items": {
+        "type": "object",
+        "properties": {
+          "uri": { "type": "string", "format": "uri" },
+          "name": { "type": "string" },
+          "mimeType": { "type": "string" },
+          "description": { "type": "string" }
+        },
+        "required": ["uri", "name"],
+        "additionalProperties": false
+      }
+    },
+    "prompts": {
+      "type": "array",
+      "description": "MCP prompts provided by servers",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "arguments": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "description": { "type": "string" },
+                "required": { "type": "boolean" }
+              }
+            }
+          }
+        },
+        "required": ["name"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/v0.5/extensions/memory/memory.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.4/extensions/memory.schema.json",
+  "title": "OSSA Memory Management Extension",
+  "description": "Extension schema for agent memory file management. Manages CLAUDE.md hierarchy, rules extraction, conditional loading, and auto-memory for IDE/CLI tools (Claude Code, Cursor, Windsurf).",
+  "$ref": "../../agent.schema.json#/definitions/MemoryManagement"
+}

package/spec/v0.5/extensions/team/team.schema.json

@@ -0,0 +1,304 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.4/extensions/team.json",
+  "title": "OSSA Team Extension Schema",
+  "description": "Validates team/config.json generated by the TeamGeneratorService. Defines multi-agent team structure, coordination model, and deployment configuration for OSSA agent teams.",
+  "type": "object",
+  "required": ["name", "version", "pattern"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Team name, typically derived from the lead agent manifest metadata.name"
+    },
+    "version": {
+      "type": "string",
+      "description": "Team configuration version",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "examples": ["1.0.0"]
+    },
+    "pattern": {
+      "type": "string",
+      "description": "Multi-agent architecture pattern governing team coordination",
+      "enum": [
+        "single",
+        "swarm",
+        "pipeline",
+        "graph",
+        "hierarchical",
+        "reactive",
+        "cognitive",
+        "lead-teammate"
+      ]
+    },
+    "lead": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "null" }
+      ],
+      "description": "Name of the lead/orchestrator agent. Null when no explicit lead is designated."
+    },
+    "members": {
+      "type": "array",
+      "description": "Team member agent definitions",
+      "items": {
+        "$ref": "#/definitions/TeamMember"
+      }
+    },
+    "coordination": {
+      "$ref": "#/definitions/Coordination",
+      "description": "Task coordination and communication configuration"
+    },
+    "deployment": {
+      "$ref": "#/definitions/Deployment",
+      "description": "Deployment backend and scaling configuration"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "TeamMember": {
+      "type": "object",
+      "description": "A single team member agent definition",
+      "required": ["name", "kind"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique agent name within the team"
+        },
+        "kind": {
+          "type": "string",
+          "description": "Agent kind/role classification within the team",
+          "examples": [
+            "team-lead",
+            "orchestrator",
+            "coordinator",
+            "teammate",
+            "worker",
+            "specialist",
+            "subagent",
+            "reviewer",
+            "planner",
+            "monitor",
+            "analyst"
+          ]
+        },
+        "role": {
+          "type": "string",
+          "description": "Human-readable role description or system prompt summary"
+        },
+        "contextIsolation": {
+          "type": "boolean",
+          "description": "Whether this agent operates with an independent context window (true) or shares context with lead (false)",
+          "default": true
+        },
+        "model": {
+          "type": "object",
+          "description": "LLM model configuration override for this member",
+          "properties": {
+            "provider": { "type": "string" },
+            "model": { "type": "string" },
+            "temperature": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 2
+            },
+            "maxTokens": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "additionalProperties": true
+        },
+        "tools": {
+          "type": "array",
+          "description": "Tools available to this member",
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string" },
+                  "description": { "type": "string" }
+                },
+                "required": ["name"]
+              }
+            ]
+          }
+        },
+        "handoffs": {
+          "type": "array",
+          "description": "Handoff targets for this member (swarm/graph patterns)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "to": {
+                "type": "string",
+                "description": "Target agent name"
+              },
+              "condition": {
+                "type": "string",
+                "description": "Condition triggering the handoff",
+                "default": "any"
+              }
+            },
+            "required": ["to"],
+            "additionalProperties": true
+          }
+        },
+        "permissions": {
+          "type": "object",
+          "description": "Team-level permissions for this member",
+          "properties": {
+            "spawn": { "type": "boolean", "description": "Can spawn new agents" },
+            "shutdown": { "type": "boolean", "description": "Can shut down agents" },
+            "assignTasks": { "type": "boolean", "description": "Can assign tasks to others" },
+            "broadcast": { "type": "boolean", "description": "Can broadcast to all members" },
+            "modifyTeam": { "type": "boolean", "description": "Can modify team configuration" },
+            "approveWork": { "type": "boolean", "description": "Can approve completed work" },
+            "rejectWork": { "type": "boolean", "description": "Can reject completed work" },
+            "claimTasks": { "type": "boolean", "description": "Can self-claim tasks" },
+            "messagePeers": { "type": "boolean", "description": "Can message peer agents" },
+            "messageLeader": { "type": "boolean", "description": "Can message team lead" },
+            "reportToParent": { "type": "boolean", "description": "Can report to parent agent" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "Coordination": {
+      "type": "object",
+      "description": "Coordination model governing how team members interact and synchronize",
+      "properties": {
+        "taskModel": {
+          "type": "string",
+          "description": "Task coordination strategy",
+          "enum": [
+            "shared-list",
+            "self-claim",
+            "assigned",
+            "handoff",
+            "event-driven",
+            "pipeline"
+          ],
+          "default": "shared-list"
+        },
+        "communication": {
+          "type": "string",
+          "description": "Inter-agent communication pattern",
+          "enum": [
+            "mailbox",
+            "broadcast",
+            "direct",
+            "shared-file",
+            "report-to-parent",
+            "pub-sub",
+            "request-reply"
+          ],
+          "default": "mailbox"
+        },
+        "conflictResolution": {
+          "type": "string",
+          "description": "Strategy for resolving conflicts between agents",
+          "enum": [
+            "leader-decides",
+            "voting",
+            "priority-based",
+            "first-writer-wins",
+            "merge",
+            "escalate"
+          ],
+          "default": "leader-decides"
+        },
+        "taskPersistence": {
+          "type": "string",
+          "description": "How task state is persisted across agent restarts",
+          "enum": [
+            "in-memory",
+            "file-backed",
+            "database",
+            "distributed"
+          ],
+          "default": "file-backed"
+        },
+        "dependencyTracking": {
+          "type": "boolean",
+          "description": "Whether task dependencies (blocks/blockedBy) are tracked and enforced",
+          "default": true
+        },
+        "waveExecution": {
+          "type": "boolean",
+          "description": "Whether tasks are executed in dependency waves (all tasks in a wave start concurrently, next wave starts when current completes)",
+          "default": true
+        },
+        "lockingStrategy": {
+          "type": "string",
+          "description": "Concurrency control strategy for shared resources",
+          "enum": [
+            "none",
+            "file-lock",
+            "advisory-lock",
+            "optimistic",
+            "pessimistic",
+            "distributed-lock"
+          ],
+          "default": "file-lock"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Deployment": {
+      "type": "object",
+      "description": "Deployment configuration for the agent team",
+      "properties": {
+        "backend": {
+          "type": "string",
+          "description": "Execution backend for agent processes",
+          "enum": [
+            "in-process",
+            "subprocess",
+            "docker",
+            "kubernetes",
+            "serverless",
+            "cloud-run",
+            "remote"
+          ],
+          "default": "in-process"
+        },
+        "scaling": {
+          "type": "string",
+          "description": "Scaling strategy for team members",
+          "enum": [
+            "fixed",
+            "auto",
+            "manual",
+            "event-driven",
+            "queue-based"
+          ],
+          "default": "fixed"
+        },
+        "minReplicas": {
+          "type": "integer",
+          "description": "Minimum number of agent replicas (for auto-scaling)",
+          "minimum": 0
+        },
+        "maxReplicas": {
+          "type": "integer",
+          "description": "Maximum number of agent replicas (for auto-scaling)",
+          "minimum": 1
+        },
+        "resources": {
+          "type": "object",
+          "description": "Resource constraints per agent process",
+          "properties": {
+            "cpu": { "type": "string", "description": "CPU limit (e.g., '500m', '2')" },
+            "memory": { "type": "string", "description": "Memory limit (e.g., '512Mi', '2Gi')" },
+            "gpu": { "type": "string", "description": "GPU requirement (e.g., 'nvidia-a100')" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}