aionmcp copilot-instructions.md

AionMCP - Autonomous Go MCP Server

Project Overview

AionMCP is an autonomous Go-based Model Context Protocol (MCP) server that dynamically imports OpenAPI, GraphQL, and AsyncAPI specifications and exposes them as tools to agents. Features self-learning, context-awareness, and auto-documentation using Clean/Hexagonal architecture.

Project Structure

cmd/                     # Application entry points
internal/core/           # Core business logic
internal/adapters/       # External integrations
internal/registry/       # Tool registration system
internal/selflearn/      # Learning and reflection engine
pkg/agent/              # Agent integration APIs
docs/                   # Auto-generated documentation
data/feedback/          # Learning data storage

Core Libraries & Dependencies

• API Framework: github.com/gin-gonic/gin
• gRPC: google.golang.org/grpc
• Plugin System: github.com/hashicorp/go-plugin
• Configuration: github.com/spf13/viper
• Logging: go.uber.org/zap
• Storage: github.com/boltdb/bolt, github.com/dgraph-io/badger
• Task Queue: github.com/hibiken/asynq
• Metrics: github.com/prometheus/client_golang

MCP Protocol Implementation

Core interfaces follow this pattern:

type Tool interface {
    Name() string
    Description() string
    Execute(input any) (any, error)
}

type ToolRegistry struct {
    mu    sync.RWMutex
    tools map[string]Tool
}

MCP envelope format:

{
  "protocol": "MCP/1.0",
  "type": "tool_call",
  "tool": "openapi.petstore.listPets",
  "args": { "limit": 10 },
  "context": { "session": "abc123" }
}

Development Iterations

Iteration 0: Project Scaffolding

Goal: Base MCP server structure Outputs: cmd/server/main.go, internal/core/server.go, registry stub, docs/README.md, docs/architecture.md

Iteration 1: Spec Importer Layer

Goal: Multi-format API spec parsing Outputs: pkg/importer/{openapi,graphql,asyncapi}.go, docs/spec_importer.md Constraints: Go interfaces, hot-reloadable, cached tools

func ImportOpenAPI(path string) ([]Tool, error) {
    spec, err := openapi3.NewLoader().LoadFromFile(path)
    if err != nil { return nil, err }
    var tools []Tool
    for name, op := range spec.Paths {
        tools = append(tools, NewOpenAPITool(name, op))
    }
    return tools, nil
}