@bluefly/openstandardagents 0.3.5 → 0.4.0

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

@@ -0,0 +1,276 @@
+# MCP (Model Context Protocol) Extension
+
+**Version**: 0.3.5
+**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.3.5
+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.3.5
+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:pass@localhost:5432/db"
+          capabilities:
+            tools:
+              listChanged: false
+```
+
+### 3. Custom MCP Resources
+
+```yaml
+apiVersion: ossa/v0.3.5
+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.3.5 Specification](../../README.md)

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

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.5/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/templates/agent-types/analyzer/cost-analyzer.yaml

@@ -0,0 +1,38 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: cost-analyzer
+  version: 1.0.0
+  description: Cost analysis agent that tracks infrastructure costs, identifies optimization opportunities, and generates cost reports
+  labels:
+    ossa.ai/type: analyzer
+    ossa.ai/domain: infrastructure
+spec:
+  role: Cost Analysis Agent
+  system_message: |
+    You are a cost analysis agent that tracks infrastructure spending, analyzes 
+    cost trends, identifies optimization opportunities, and generates detailed 
+    cost reports with recommendations.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.1
+  tools:
+    - name: get_cost_data
+      description: Retrieve infrastructure cost data
+      parameters:
+        type: object
+        properties:
+          period:
+            type: string
+          service:
+            type: string
+  taxonomy:
+    domain: infrastructure
+    subdomain: cost
+    capability: cost_analysis
+    concerns: [cost, performance]
+    maturity: stable
+    deployment_pattern: serverless
+    integration_pattern: api-first
+    cost_profile: low
+    performance_tier: batch

package/templates/agent-types/analyzer/performance-profiler.yaml

@@ -0,0 +1,38 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: performance-profiler
+  version: 1.0.0
+  description: Performance profiling agent that analyzes application performance, identifies bottlenecks, and recommends optimizations
+  labels:
+    ossa.ai/type: analyzer
+    ossa.ai/domain: development
+spec:
+  role: Performance Profiling Agent
+  system_message: |
+    You are a performance profiling agent that analyzes application performance 
+    metrics, identifies bottlenecks, profiles code execution, and provides 
+    actionable optimization recommendations.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.2
+  tools:
+    - name: profile_application
+      description: Profile application performance
+      parameters:
+        type: object
+        properties:
+          application:
+            type: string
+          duration:
+            type: integer
+  taxonomy:
+    domain: development
+    subdomain: performance
+    capability: profiling
+    concerns: [performance, quality]
+    maturity: beta
+    deployment_pattern: container
+    integration_pattern: api-first
+    cost_profile: medium
+    performance_tier: near-real-time

package/templates/agent-types/analyzer/security-scanner.yaml

@@ -0,0 +1,36 @@
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: security-scanner
+  description: "Security vulnerability scanner that analyzes code and dependencies for security issues"
+  labels:
+    domain: security
+    type: analyzer
+    tags: security,vulnerability,scanning
+spec:
+  role: "You are a security scanner agent. Analyze code, dependencies, and configurations for security vulnerabilities, compliance issues, and best practices."
+  llm:
+    provider: openai
+    model: gpt-4
+    temperature: 0.2
+    maxTokens: 2000
+  taxonomy:
+    domain: security
+    subdomain: vulnerability
+    maturity: stable
+    deploymentPattern: container
+    integrationPattern: batch
+    costProfile: low
+    performanceTier: batch
+  tools:
+    - type: mcp
+      name: filesystem
+      server: filesystem-server
+    - type: api
+      name: vulnerability-database
+      endpoint: https://api.nvd.nist.gov/vuln
+  constraints:
+    cost:
+      maxTokensPerDay: 50000
+      maxCostPerDay: 25
+      currency: USD

package/templates/agent-types/backend/api-validator.yaml

@@ -0,0 +1,37 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: api-validator
+  version: 1.0.0
+  description: API validation agent that validates API contracts, checks OpenAPI compliance, and ensures API consistency
+  labels:
+    ossa.ai/type: analyzer
+    ossa.ai/domain: backend
+spec:
+  role: API Validation Agent
+  system_message: |
+    You are an API validation agent that validates API contracts, checks OpenAPI 
+    compliance, ensures API consistency, and validates request/response schemas.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.1
+  tools:
+    - name: validate_api
+      description: Validate API against specification
+      parameters:
+        type: object
+        properties:
+          api_spec:
+            type: string
+          endpoint:
+            type: string
+  taxonomy:
+    domain: backend
+    subdomain: api
+    capability: api_validation
+    concerns: [quality, architecture]
+    maturity: stable
+    deployment_pattern: container
+    integration_pattern: api-first
+    cost_profile: low
+    performance_tier: near-real-time

package/templates/agent-types/backend/load-balancer.yaml

@@ -0,0 +1,39 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: load-balancer
+  version: 1.0.0
+  description: Load balancing agent that distributes traffic, manages routing, and optimizes request distribution
+  labels:
+    ossa.ai/type: orchestrator
+    ossa.ai/domain: backend
+spec:
+  role: Load Balancing Agent
+  system_message: |
+    You are a load balancing agent that distributes traffic across multiple 
+    instances, manages routing decisions, and optimizes request distribution 
+    for performance and reliability.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.2
+  tools:
+    - name: route_request
+      description: Route request to instance
+      parameters:
+        type: object
+        properties:
+          request:
+            type: object
+          algorithm:
+            type: string
+            enum: [round-robin, least-connections, weighted]
+  taxonomy:
+    domain: backend
+    subdomain: networking
+    capability: load_balancing
+    concerns: [performance, reliability]
+    maturity: production
+    deployment_pattern: container
+    integration_pattern: event-driven
+    cost_profile: high
+    performance_tier: real-time

package/templates/agent-types/content/content-generator.yaml

@@ -0,0 +1,40 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: content-generator
+  version: 1.0.0
+  description: Content generation agent that creates written content, articles, and documentation
+  labels:
+    ossa.ai/type: worker
+    ossa.ai/domain: content
+spec:
+  role: Content Generation Agent
+  system_message: |
+    You are a content generation agent that creates high-quality written content, 
+    articles, blog posts, documentation, and marketing materials.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+  tools:
+    - name: generate_content
+      description: Generate content from prompt
+      parameters:
+        type: object
+        properties:
+          content_type:
+            type: string
+            enum: [article, blog, documentation, marketing]
+          topic:
+            type: string
+          length:
+            type: integer
+  taxonomy:
+    domain: content
+    subdomain: generation
+    capability: content_creation
+    concerns: [quality]
+    maturity: stable
+    deployment_pattern: serverless
+    integration_pattern: api-first
+    cost_profile: medium
+    performance_tier: near-real-time

package/templates/agent-types/content/seo-optimizer.yaml

@@ -0,0 +1,39 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: seo-optimizer
+  version: 1.0.0
+  description: SEO optimization agent that optimizes content for search engines, analyzes keywords, and improves rankings
+  labels:
+    ossa.ai/type: analyzer
+    ossa.ai/domain: content
+spec:
+  role: SEO Optimization Agent
+  system_message: |
+    You are an SEO optimization agent that optimizes content for search engines, 
+    analyzes keywords, suggests improvements, and monitors SEO performance.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.3
+  tools:
+    - name: analyze_seo
+      description: Analyze SEO metrics
+      parameters:
+        type: object
+        properties:
+          url:
+            type: string
+          keywords:
+            type: array
+            items:
+              type: string
+  taxonomy:
+    domain: content
+    subdomain: seo
+    capability: seo_optimization
+    concerns: [quality, performance]
+    maturity: beta
+    deployment_pattern: serverless
+    integration_pattern: api-first
+    cost_profile: low
+    performance_tier: near-real-time

package/templates/agent-types/data/data-processor.yaml

@@ -0,0 +1,38 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: data-processor
+  version: 1.0.0
+  description: Data processing agent that processes datasets, transforms data, and generates insights
+  labels:
+    ossa.ai/type: worker
+    ossa.ai/domain: data
+spec:
+  role: Data Processing Agent
+  system_message: |
+    You are a data processing agent that processes datasets, transforms data formats, 
+    cleans data, and generates insights from structured and unstructured data.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.2
+  tools:
+    - name: process_data
+      description: Process dataset
+      parameters:
+        type: object
+        properties:
+          dataset:
+            type: string
+          operation:
+            type: string
+            enum: [transform, clean, aggregate, analyze]
+  taxonomy:
+    domain: data
+    subdomain: processing
+    capability: data_processing
+    concerns: [performance, quality]
+    maturity: stable
+    deployment_pattern: container
+    integration_pattern: batch
+    cost_profile: medium
+    performance_tier: batch