feat(mcp): Add OpenAPI MCP server POC

[andmatei]

Summary

This PR adds a Model Context Protocol (MCP) server POC for the FOAS CLI that enables AI agents to load, filter, and explore OpenAPI specifications.

Features

Tools

• load_spec - Load an OpenAPI spec from disk
• filter_spec - Filter a spec by tags, operation IDs, or paths
• export_spec - Save a spec to disk (JSON or YAML)
• unload_spec - Remove a spec from memory
• list_specs - List all loaded specs

Resources

List Resources:

• openapi://{alias}/operations - List all operations
• openapi://{alias}/tags - List all tags
• openapi://{alias}/paths - List all paths
• openapi://{alias}/schemas - List all schemas

Detail Resources:

• openapi://{alias}/operations/{operationId} - Get operation details
• openapi://{alias}/tags/{tagName} - Get operations for a tag
• openapi://{alias}/paths/{path} - Get operations for a path
• openapi://{alias}/schemas/{schemaName} - Get schema definition

Usage

Build

cd tools/cli
make build-mcp

Configure with Augment

{
  "mcpServers": {
    "openapi": {
      "command": "/path/to/openapi-mcp"
    }
  }
}

Implementation Details

• Uses the official MCP Go SDK (github.com/modelcontextprotocol/go-sdk)
• Reuses existing slice.Slice() for filtering
• Reuses existing openapi.Save() for export
• In-memory registry with max 50 specs
• Full test coverage (25 tests)

Files Changed

• tools/cli/cmd/mcp/main.go - Entry point
• tools/cli/internal/mcp/registry/ - Spec storage
• tools/cli/internal/mcp/tools/ - MCP tools
• tools/cli/internal/mcp/resources/ - MCP resources
• tools/cli/Makefile - Build targets

---

Pull Request opened by Augment Code with guidance from the PR author