← Documentation Home

Agent Protocol Developer Guide

Overview

Package: @bluefly/agent-protocol Version: Latest License: MIT

Model Context Protocol (MCP) server and OSSA 1.0 protocol implementation for the Bluefly LLM Ecosystem. Integration hub for tool registration, context routing, OpenAPI synchronization, and server introspection.

Key Features

Installation

npm install @bluefly/agent-protocol

Quick Start

As an MCP Server

import { createMCPServer } from '@bluefly/agent-protocol';

const server = await createMCPServer({
  name: 'my-mcp-server',
  version: '1.0.0',
  security: {
    enabled: true,
    apiKey: process.env.API_KEY,
  },
});

// Register tools
server.registerTool({
  name: 'my-tool',
  description: 'My custom tool',
  schema: {
    type: 'object',
    properties: {
      input: { type: 'string' }
    },
    required: ['input']
  },
  handler: async (params) => {
    return { result: 'success', output: params.input };
  },
});

await server.start();

MCPB CLI

MCP Build Tool for managing installations:

# Show version
node cli/index.js --version

# Configure Claude Desktop
node cli/index.js claude configure

# Check connection
node cli/index.js claude status

# Test MCP connection
node cli/index.js claude test

# Server operations
node cli/index.js server start
node cli/index.js server stop
node cli/index.js server status

MCPB Commands

Command Description
install Install MCPB and configure Claude Desktop
configure Reconfigure MCPB settings
status Check MCPB status and platform connection
test Test MCPB connection and features
uninstall Uninstall MCPB from Claude Desktop

API Reference

Tool Registration

// Register tool
server.registerTool({
  name: 'calculate',
  description: 'Perform mathematical calculations',
  schema: {
    type: 'object',
    properties: {
      expression: { type: 'string' },
      precision: { type: 'number', default: 2 }
    },
    required: ['expression']
  },
  handler: async ({ expression, precision = 2 }) => {
    const result = eval(expression);
    return { result: result.toFixed(precision) };
  }
});

Context Management

// Set context
await server.setContext({
  key: 'user-preferences',
  value: {
    theme: 'dark',
    language: 'en'
  },
  scope: 'session'
});

// Get context
const context = await server.getContext('user-preferences');

Security & Policy

import { PolicyEngine } from '@bluefly/agent-protocol/policy';

const policy = new PolicyEngine({
  policyPath: './policies',
  enforceMode: 'strict',
});

// Evaluate policy
const allowed = await policy.evaluate({
  user: 'user-id',
  action: 'execute-tool',
  resource: 'my-tool',
});

Audit & Tracing

import { AuditLogger } from '@bluefly/agent-protocol/audit';

const audit = new AuditLogger({
  storage: 'redis',
  redis: {
    host: 'localhost',
    port: 6379,
  },
});

await audit.log({
  event: 'tool-execution',
  user: 'user-id',
  tool: 'my-tool',
  result: 'success',
});

Configuration

Environment Variables

# MCP Server
MCP_SERVER_PORT=3001
MCP_SERVER_ENABLED=true

# Security
API_KEY_ENABLED=true
JWT_SECRET=your-jwt-secret

# Observability
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PROMETHEUS_PORT=9090

MCPB Configuration

~/.mcpb/config.json:

{
  "platform": {
    "url": "https://your-platform.example.com",
    "apiKey": "your-api-key"
  },
  "claude": {
    "configPath": "~/Library/Application Support/Claude/claude_desktop_config.json"
  }
}

Examples

Tool with Validation

server.registerTool({
  name: 'create-user',
  description: 'Create a new user account',
  schema: {
    type: 'object',
    properties: {
      email: { 
        type: 'string', 
        format: 'email' 
      },
      name: { 
        type: 'string',
        minLength: 2
      },
      role: {
        type: 'string',
        enum: ['admin', 'user', 'guest']
      }
    },
    required: ['email', 'name']
  },
  handler: async ({ email, name, role = 'user' }) => {
    // Validate with policy engine
    const allowed = await policy.evaluate({
      action: 'create-user',
      role: role
    });

    if (!allowed) {
      throw new Error('Insufficient permissions');
    }

    // Create user
    const user = await createUser({ email, name, role });

    // Audit log
    await audit.log({
      event: 'user-created',
      userId: user.id
    });

    return { success: true, userId: user.id };
  }
});

Server Introspection

// List all registered tools
const tools = await server.listTools();

// Get server capabilities
const capabilities = await server.getCapabilities();

// Health check
const health = await server.healthCheck();

Observability

Phoenix Arize

# View MCP traces
open http://localhost:6006

# Monitor tool performance
curl http://localhost:3000/api/observability/mcp

Prometheus Metrics

# Export metrics
curl http://localhost:9090/metrics

# Key metrics:
# - mcp_tool_invocations_total
# - mcp_tool_duration_seconds
# - mcp_context_operations_total
# - ossa_agent_operations_total

OSSA 1.0 Compliance

# Validate compliance
npm run ossa:validate

# Generate OSSA docs
npm run ossa:docs

# Check agent health
npm run ossa:health

Deployment

Kubernetes

kubectl create namespace agent-protocol
kubectl apply -f infrastructure/kubernetes/ -n agent-protocol
kubectl get pods -n agent-protocol

Docker

docker build -t bluefly/agent-protocol:latest .
docker run -d -p 3001:3001 bluefly/agent-protocol:latest

Testing

npm test
npm run test:integration
npm run test:coverage

Documentation