ayaiay MCP Server

The ayaiay MCP Server is a .NET implementation of the Model Context Protocol (MCP) that provides programmatic access to all ayaiay functionality.

What is ayaiay MCP?

ayaiay MCP is an MCP server that exposes the same capabilities as the ayaiay CLI through the Model Context Protocol. This enables seamless integration with MCP-compatible tools like:

• Claude Desktop: Use ayaiay directly in Claude conversations
• Cline: Integrate pack management into your coding workflow
• Continue: Access packs from your IDE
• Custom MCP Clients: Build your own integrations

What is MCP?

The Model Context Protocol is an open standard for connecting AI applications to data sources and tools. MCP servers provide:

• Tools: Functions that can be called by AI assistants
• Resources: Structured data that can be queried
• Prompts: Reusable prompt templates

ayaiay MCP implements all three, giving AI assistants full access to the ayaiay ecosystem.

Key Features

Complete CLI Functionality

All CLI commands are available as MCP tools:

• Search for packs
• Install and manage packs
• Validate manifests
• Query pack information

Resource Access

MCP resources provide structured access to:

• Installed packs
• Pack metadata and versions
• Agent and instruction contents
• Prompt templates

Prompt Templates

Pre-built prompts for common tasks:

• Finding relevant packs
• Installing recommended packs
• Validating pack manifests
• Creating new packs

Multiple Transport Protocols

Supports all MCP transport protocols:

• STDIO: Standard input/output for local processes
• HTTP with SSE: Server-sent events for web integration
• WebSocket: Real-time bidirectional communication

Quick Start

Prerequisites

• .NET 8.0 SDK or higher
• An MCP-compatible client (e.g., Claude Desktop)

Installation

# Clone the repository
git clone https://github.com/ayaiayorg/ayaiay-mcp.git
cd ayaiay-mcp

# Restore dependencies
dotnet restore

# Build the project
dotnet build

# Run the server
dotnet run --project src/AyaiayMcp

Configuration for Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ayaiay": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/path/to/ayaiay-mcp/src/AyaiayMcp"
      ],
      "env": {
        "AYAIAY_API_URL": "https://ayaiay.org"
      }
    }
  }
}

Configuration for Other MCP Clients

For Cline, Continue, or other MCP clients, follow their specific configuration instructions using the command and arguments above.

Available Tools

The MCP server provides the following tools:

search_packs

Search for packs in the catalog.

Parameters:

• query (string, optional): Search term
• limit (integer, optional): Maximum results (default: 10)

Example:

{
  "query": "code review",
  "limit": 20
}

install_pack

Install a pack from the catalog.

Parameters:

• pack (string, required): Pack identifier (e.g., publisher/pack@version)
• target (string, optional): Installation directory

Example:

{
  "pack": "acme/code-reviewer@1.2.0",
  "target": "/path/to/install"
}

validate_manifest

Validate an ayaiay.yaml manifest file.

Parameters:

• path (string, required): Path to the manifest file

Example:

{
  "path": "/path/to/ayaiay.yaml"
}

list_installed

List all installed packs.

Parameters: None

get_pack_info

Get detailed information about a pack.

Parameters:

• pack (string, required): Pack identifier

Example:

{
  "pack": "acme/code-reviewer"
}

update_pack

Update an installed pack to the latest version.

Parameters:

• pack (string, required): Pack identifier

Example:

{
  "pack": "acme/code-reviewer"
}

uninstall_pack

Uninstall a pack.

Parameters:

• pack (string, required): Pack identifier

Example:

{
  "pack": "acme/code-reviewer"
}

get_agent_content

Retrieve the content of a specific agent from an installed pack.

Parameters:

• pack (string, required): Pack identifier
• agent (string, required): Agent name

Example:

{
  "pack": "acme/code-reviewer",
  "agent": "senior-reviewer"
}

get_instruction_content

Retrieve the content of a specific instruction from an installed pack.

Parameters:

• pack (string, required): Pack identifier
• instruction (string, required): Instruction name

get_prompt_template

Retrieve a prompt template from an installed pack.

Parameters:

• pack (string, required): Pack identifier
• prompt (string, required): Prompt name

Available Resources

MCP resources provide read-only access to structured data:

packs://installed

List all installed packs with metadata.

URI: packs://installed

Returns:

{
  "packs": [
    {
      "name": "code-reviewer",
      "publisher": "acme",
      "version": "1.2.0",
      "installed_path": "/path/to/packs/acme/code-reviewer",
      "installed_at": "2024-01-20T10:30:00Z"
    }
  ]
}

pack://[publisher]/[name]

Get detailed information about a specific pack.

URI: pack://acme/code-reviewer

Returns:

{
  "name": "code-reviewer",
  "publisher": "acme",
  "version": "1.2.0",
  "description": "AI agents for code review",
  "agents": ["senior-reviewer", "junior-reviewer"],
  "instructions": ["review-guidelines"],
  "prompts": ["review-prompt"],
  "manifest": { ... }
}

agent://[publisher]/[pack]/[agent]

Get a specific agent's content.

URI: agent://acme/code-reviewer/senior-reviewer

Returns: The agent's instruction content as markdown.

instruction://[publisher]/[pack]/[instruction]

Get a specific instruction's content.

URI: instruction://acme/code-reviewer/review-guidelines

prompt://[publisher]/[pack]/[prompt]

Get a specific prompt template.

URI: prompt://acme/code-reviewer/review-prompt

Available Prompts

MCP prompts provide reusable templates:

find-pack

Help find a relevant pack based on a description.

Arguments:

• description (string): What you're looking for

install-pack-wizard

Interactive wizard to install a pack.

Arguments:

• pack_name (string): Name of the pack to install

create-pack-template

Generate a template for creating a new pack.

Arguments:

• pack_type (string): Type of pack (agent, instruction, prompt, mcp)

Configuration

Environment Variables

Variable	Description	Default
AYAIAY_API_URL	ayaiay API base URL	https://ayaiay.org
AYAIAY_INSTALL_DIR	Default installation directory	~/.ayaiay/packs
AYAIAY_CACHE_ENABLED	Enable response caching	true
AYAIAY_CACHE_TTL	Cache time-to-live (seconds)	3600
MCP_TRANSPORT	Transport protocol (stdio/http/ws)	stdio
MCP_HTTP_PORT	HTTP server port (if using HTTP)	8080

Server Configuration

Create appsettings.json for advanced configuration:

{
  "Ayaiay": {
    "ApiUrl": "https://ayaiay.org",
    "InstallDirectory": "~/.ayaiay/packs",
    "CacheEnabled": true,
    "CacheTtl": 3600
  },
  "Mcp": {
    "Transport": "stdio",
    "HttpPort": 8080,
    "EnableCors": true,
    "AllowedOrigins": ["http://localhost:3000"]
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    }
  }
}

Usage Examples

Example 1: Search and Install via Claude Desktop

Once configured, you can use natural language:

User: Find me a code review pack
Claude: [Uses search_packs tool with query "code review"]
        I found several code review packs. The most popular is acme/code-reviewer.

User: Install it
Claude: [Uses install_pack tool with pack "acme/code-reviewer"]
        I've installed acme/code-reviewer v1.2.0 successfully.

Example 2: Validate Manifest

User: Validate the manifest in my current project
Claude: [Uses validate_manifest tool with path "./ayaiay.yaml"]
        Your manifest is valid! Pack: my-agent-pack, Version: 1.0.0

Example 3: Get Agent Content

User: Show me the senior reviewer agent instructions
Claude: [Uses get_agent_content tool]
        Here are the instructions for the senior reviewer agent: [content]

Integration Examples

.NET Application

using AyaiayMcp;

// Create MCP client
var client = new McpClient("http://localhost:8080");

// Search for packs
var results = await client.SearchPacksAsync("code review");

// Install a pack
await client.InstallPackAsync("acme/code-reviewer@1.2.0");

// Get pack info
var info = await client.GetPackInfoAsync("acme/code-reviewer");

TypeScript/JavaScript

import { MCPClient } from '@modelcontextprotocol/sdk';

// Connect to MCP server
const client = new MCPClient({
  transport: 'stdio',
  command: 'dotnet',
  args: ['run', '--project', '/path/to/ayaiay-mcp']
});

// Use tools
const results = await client.callTool('search_packs', {
  query: 'code review',
  limit: 10
});

// Read resources
const installed = await client.readResource('packs://installed');

Python

from mcp import MCPClient

# Create client
client = MCPClient(
    transport='stdio',
    command='dotnet',
    args=['run', '--project', '/path/to/ayaiay-mcp']
)

# Search packs
results = client.call_tool('search_packs', {
    'query': 'code review',
    'limit': 10
})

# Read resource
installed = client.read_resource('packs://installed')

Architecture

Component Overview

ayaiay-mcp/
├── src/
│   └── AyaiayMcp/
│       ├── Program.cs              # Entry point
│       ├── McpServer.cs            # MCP protocol implementation
│       ├── Tools/                  # Tool implementations
│       │   ├── SearchPacksTool.cs
│       │   ├── InstallPackTool.cs
│       │   └── ...
│       ├── Resources/              # Resource providers
│       │   ├── PacksResource.cs
│       │   ├── AgentResource.cs
│       │   └── ...
│       ├── Prompts/                # Prompt templates
│       │   ├── FindPackPrompt.cs
│       │   └── ...
│       ├── Services/               # Core services
│       │   ├── PackService.cs
│       │   ├── ApiClient.cs
│       │   └── FileSystemService.cs
│       └── Models/                 # Data models
├── tests/                          # Unit tests
└── docs/                           # Documentation

Technology Stack

• .NET 8.0: Core runtime
• System.Text.Json: JSON serialization
• HttpClient: API communication
• Microsoft.Extensions.Hosting: Dependency injection and configuration
• MCP.NET: MCP protocol library (custom implementation)

Best Practices

For Tool Providers

• Validate Input: Always validate tool parameters
• Handle Errors Gracefully: Return meaningful error messages
• Log Operations: Log all tool calls for debugging
• Cache Responses: Cache API responses to reduce latency

For Resource Providers

• Keep Resources Lightweight: Avoid loading large datasets
• Use Pagination: Implement pagination for large collections
• Cache Resource Data: Cache frequently accessed resources
• Version Resources: Support resource versioning

For Prompt Authors

• Be Specific: Provide clear, specific prompts
• Include Examples: Show example inputs and outputs
• Handle Edge Cases: Consider error scenarios
• Test Thoroughly: Test prompts with various inputs

Troubleshooting

Server Won't Start

Check:

• .NET SDK is installed (dotnet --version)
• All dependencies are restored (dotnet restore)
• No port conflicts (if using HTTP transport)
• Configuration file is valid JSON

Tool Calls Fail

Common issues:

• Invalid API URL in configuration
• Network connectivity problems
• Missing permissions for file operations
• Invalid pack identifiers or versions

Resource Access Fails

Check:

• Pack is installed locally
• File permissions are correct
• Resource URI is properly formatted
• Pack structure matches specification

Next Steps

• Installation Guide - Detailed setup instructions
• Configuration Guide - Advanced configuration
• Tools Reference - Complete tool documentation
• Integration Guide - Build custom integrations
• CLI Documentation - Learn about the CLI alternative