Tool Providers & Plugin System

Active Development

The tool provider system and plugin architecture are evolving. The built-in providers are stable. The external plugin loading system exists but is not yet widely adopted.

Aether uses a tool provider abstraction to decouple external integrations from the core platform. Each integration implements a standard interface that the Hub discovers and executes at runtime — including via MCP (Model Context Protocol) servers.

Overview

The tool system pipeline:

Webhook → Unified Handler → Task Resolution → LLM (with tool schemas) → Tool Execution → Response

Tools are:

• Defined in the database — Tool definitions describe capabilities, parameters, and providers
• Registered via built-in providers or plugins — Each integration implements the ToolProvider interface
• Extended via MCP — External MCP servers dynamically add tools at runtime
• Discovered at runtime — The tool registry resolves available tools per context
• Exposed to LLM — Tool schemas are injected into LLM prompts for function calling (always enabled)

Tool Provider Interface

Every integration plugin implements the provider interface defined in goway/pkg/sdk/:

// Provider is the interface that all tool providers must implement
type Provider interface {
    // Info returns metadata about the provider
    Info() ProviderInfo

    // Tools returns the list of tools this provider offers
    Tools() []ToolDefinition

    // Execute runs a specific tool with the given parameters
    Execute(ctx context.Context, toolName string, params map[string]interface{}) (interface{}, error)

    // Validate checks if the provider configuration is valid
    Validate() error
}

Tool Definition

Each tool declares its name, description, and parameter schema:

type ToolDefinition struct {
    Name        string                 `json:"name"`
    Description string                 `json:"description"`
    Category    string                 `json:"category"`
    Parameters  map[string]ParamSpec   `json:"parameters"`
}

Built-in Providers

Aether ships with providers for common issue trackers:

Provider	Package	Tools
GitHub	issuetracker/github	add_comment, update_description, get_issue, create_label
GitLab	issuetracker/gitlab	add_comment, update_description, get_issue
Jira	issuetracker/jira	add_comment, update_description, get_issue, transition_issue
Plane	issuetracker/plane	add_comment, update_description, get_issue

Tool Registry

The tool registry manages discovery and resolution:

// Register a provider
registry.Register("github", githubProvider)

// Discover tools for a context
tools := registry.ToolsForProject(projectID)

// Execute a tool
result, err := registry.Execute(ctx, "github.add_comment", params)

Database-Backed Definitions

Tool definitions are stored in the tool_definitions table and can be managed via API:

# List all tool definitions
GET /api/tools

# Create a tool definition
POST /api/tools
{
  "name": "add_comment",
  "provider": "github",
  "description": "Add a comment to an issue",
  "category": "issue_tracker",
  "parameters": {
    "issue_id": {"type": "string", "required": true},
    "body": {"type": "string", "required": true}
  }
}

# Seed default tool definitions
POST /api/tools/seed

External Plugin System

Beyond built-in providers, Aether supports external plugins via the aether-integrations project:

aether-integrations/
├── sdk/                    # Plugin SDK
│   ├── provider.go         # Provider interface
│   ├── context.go          # Execution context
│   ├── credentials.go      # Credential management
│   └── manifest.go         # Plugin manifest spec
├── plugins/
│   ├── github/             # GitHub plugin
│   ├── gitlab/             # GitLab plugin
│   ├── jira/               # Jira plugin
│   └── plane/              # Plane plugin

Plugin Manifest

Each plugin declares its capabilities in a manifest:

name: github
version: 1.0.0
description: GitHub integration for Aether
author: Aether Contributors
tools:
  - name: add_comment
    description: Add a comment to a GitHub issue or PR
    parameters:
      owner: {type: string, required: true}
      repo: {type: string, required: true}
      issue_number: {type: integer, required: true}
      body: {type: string, required: true}

Unified Webhook System

The tool provider system works alongside the unified webhook handler:

Webhook Mappings

Source-specific webhooks are mapped to canonical triggers:

GitHub: "issues.opened"     → "issue.created"
GitLab: "Issue Hook.open"   → "issue.created"
Jira:   "jira:issue_created" → "issue.created"
Plane:  "issue.created"     → "issue.created"

Webhook Auth

Each mapping can configure authentication verification:

Source	Auth Method
GitHub	HMAC-SHA256 signature verification
GitLab	Secret token header
Jira	HMAC-SHA256 or IP allowlist
Plane	API key header

Admin API

# List webhook mappings
GET /api/webhook-mappings

# Create custom mapping
POST /api/webhook-mappings
{
  "source": "custom_app",
  "path_pattern": "/webhook/custom/:project",
  "extraction_rules": {
    "event_type": "$.type",
    "issue_id": "$.data.id",
    "project_id": "$.data.project"
  }
}

# Seed defaults
POST /api/webhook-mappings/seed

MCP (Model Context Protocol) Integration

Aether integrates with MCP servers to dynamically discover additional tools at runtime:

# Register an MCP server
curl -X POST http://localhost:8000/api/mcp-servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MCP Tools",
    "url": "http://mcp-server:8080",
    "agent_id": "ta_leo"   # optional: assign to a specific agent
  }'

# Discover tools from the MCP server
curl -X POST http://localhost:8000/api/mcp-servers/discover

Once registered, tools from MCP servers appear alongside built-in tools when the LLM makes tool calls.

MCP server configurations are stored in the mcp_servers table and can be assigned to specific agents.

Adding a New Tool Provider

To add a new built-in integration:

1. Implement the Provider interface in infrastructure/adapter/issuetracker/<name>/
2. Define tools with JSON parameter schemas
3. Register with the tracker registry in issuetracker/registry.go
4. Add source event mappings for the new source's webhook events
5. Seed tool definitions in the database
6. Add tests for the provider implementation
7. Test end-to-end with the LLM tool-calling flow

See Adding Integrations for a detailed step-by-step guide.

Configuration

Variable	Description
TRACKER_UPDATES_ENABLED	Enable/disable posting responses to issue trackers (default: true)
LLM_MAX_TOOL_ROUNDS	Max tool call iterations per request (default: 5)
GITHUB_TOKEN	GitHub API token
GITLAB_URL, GITLAB_TOKEN	GitLab connection details
JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN, JIRA_IS_CLOUD	Jira connection details
PLANE_API_URL, PLANE_API_KEY, PLANE_WORKSPACE_SLUG	Plane connection details