šŸŒ€
ā† Back to Articles & Artefacts
artefactswest

VSCode Toolset Registry Specification

IAIP Research
rispecs

VSCode Toolset Registry Specification

RISE Framework Specification v1.0 Document: IAIP/prototypes/artefacts/rispecs/toolset-registry.rispecs.md Status: Shared Library for mia-code, miadi-code, jgt-code

Creative Intent

The VSCode Toolset Registry empowers developers to create standardized tool discovery and management for AI coding agents. Users achieve consistent tool availability across mia-code, miadi-code, and jgt-code by defining capabilities in a unified registry format.

Structural Tension Analysis

Current Reality:

  • Each application defines its own tool interfaces
  • Claude CLI has --tools flag but no standard discovery mechanism
  • Gemini CLI tool usage is model-dependent
  • MCP servers provide tools but discovery is per-server
  • No unified way to declare "this agent has these capabilities"
  • VSCode extensions have their own contribution points

Desired Structural State:

  • Single toolsets.jsonc schema for declaring available tools
  • ToolRegistry component for runtime tool discovery and invocation
  • Agents can query available tools without knowing implementation details
  • Tools categorized by domain (coding, charts, trading, ceremonies)
  • MCP integration for external tool provision

Core Schema

toolsets.jsonc

Location: Project root or ~/.config/iaip/toolsets.jsonc

```jsonc { "$schema": "https://iaip.dev/schemas/toolsets.v1.json", "version": "1.0",

"registries": [ { "id": "core", "name": "IAIP Core Tools", "source": "builtin" }, { "id": "coaia-narrative", "name": "CoAIA Narrative MCP", "source": "mcp", "serverConfig": { "command": "npx", "args": ["coaia-narrative", "mcp"] } } ],

"toolsets": { "structural-tension": { "name": "Structural Tension Charts", "category": "ceremonial", "registry": "coaia-narrative", "tools": [ { "name": "create_structural_tension_chart", "description": "Create a new chart with desired outcome and current reality", "inputSchema": { "$ref": "#/definitions/CreateChartInput" } }, { "name": "manage_action_step", "description": "Add or expand action steps (unified interface)", "inputSchema": { "$ref": "#/definitions/ManageActionStepInput" } }, { "name": "update_current_reality", "description": "Update observations about current state", "inputSchema": { "$ref": "#/definitions/UpdateRealityInput" } } ] },

"trading": {
  "name": "Trading Memory Tools",
  "category": "domain:trading",
  "registry": "core",
  "tools": [
    {
      "name": "create_signal",
      "description": "Record a trading signal (EAST direction)",
      "inputSchema": { "$ref": "#/definitions/SignalInput" }
    },
    {
      "name": "create_wave_analysis",
      "description": "Record wave count analysis (SOUTH direction)",
      "inputSchema": { "$ref": "#/definitions/WaveInput" }
    },
    {
      "name": "check_direction_obligations",
      "description": "Verify ceremony order before execution",
      "inputSchema": { "$ref": "#/definitions/ObligationCheckInput" }
    }
  ]
},

"session": {
  "name": "Session Management",
  "category": "system",
  "registry": "core",
  "tools": [
    {
      "name": "capture_context",
      "description": "Serialize current agent context for transfer",
      "inputSchema": { "$ref": "#/definitions/CaptureContextInput" }
    },
    {
      "name": "restore_context",
      "description": "Hydrate agent from serialized context",
      "inputSchema": { "$ref": "#/definitions/RestoreContextInput" }
    }
  ]
}

},

"definitions": { "CreateChartInput": { "type": "object", "properties": { "desiredOutcome": { "type": "string" }, "currentReality": { "type": "string" }, "dueDate": { "type": "string", "format": "date" } }, "required": ["desiredOutcome", "currentReality"] } // ... additional definitions } } ```

Core Components

ToolRegistry

Purpose: Runtime discovery and invocation of registered tools.

```typescript interface ToolRegistry { // Discovery listToolsets(): Toolset[]; listTools(category?: string): Tool[]; getTool(name: string): Tool | undefined;

// Invocation invoke(toolName: string, input: unknown): Promise<ToolResult>;

// MCP Integration connectMCPServer(config: MCPServerConfig): Promise<void>; disconnectMCPServer(registryId: string): Promise<void>;

// Hot Reload reload(): Promise<void>; watch(): void; }

interface Toolset { name: string; category: string; registry: string; tools: Tool[]; enabled: boolean; }

interface Tool { name: string; description: string; inputSchema: JSONSchema; outputSchema?: JSONSchema;

// Metadata category: string; registry: string;

// Capabilities requiresConfirmation?: boolean; modifiesState?: boolean; networkAccess?: boolean; }

interface ToolResult { success: boolean; data?: unknown; error?: { code: string; message: string; }; metadata?: { executionTime: number; tokensCost?: number; }; } ```

ToolsetLoader

Purpose: Parse and validate toolsets.jsonc files.

```typescript class ToolsetLoader { // Load from file path load(configPath: string): ToolsetConfig;

// Merge multiple configs (user + project + defaults) merge(...configs: ToolsetConfig[]): ToolsetConfig;

// Validate against schema validate(config: unknown): ValidationResult;

// Resolve MCP server references resolveMCPServers(config: ToolsetConfig): Promise<ResolvedConfig>; } ```

MCPToolBridge

Purpose: Bridge MCP server tools into the unified registry.

```typescript class MCPToolBridge { constructor(serverConfig: MCPServerConfig);

// Connect to MCP server connect(): Promise<void>;

// Discover available tools discoverTools(): Promise<Tool[]>;

// Invoke tool through MCP invoke(toolName: string, input: unknown): Promise<ToolResult>;

// Handle server lifecycle disconnect(): Promise<void>; healthCheck(): Promise<boolean>; } ```

Category Taxonomy

```typescript type ToolCategory = // System Categories | 'system' // Session, context, configuration | 'file' // File operations, editing | 'terminal' // Shell commands

// Ceremonial Categories | 'ceremonial' // Structural tension, ceremonies | 'narrative' // Beats, story tracking

// Domain Categories | 'domain:trading' // Trading-specific tools | 'domain:coding' // Code analysis, refactoring | 'domain:planning' // Project planning, roadmaps

// Integration Categories | 'integration:github' // GitHub API operations | 'integration:mcp' // MCP server tools | 'integration:visualizer'; // coaia-visualizer ```

Integration Patterns

mia-code: Unified Tool Access

```typescript import { ToolRegistry, ToolsetLoader } from '@iaip/toolset-registry';

const loader = new ToolsetLoader(); const config = loader.merge( loader.load('~/.config/iaip/toolsets.jsonc'), loader.load('./toolsets.jsonc') );

const registry = new ToolRegistry(config);

// In dual-session flow const chartResult = await registry.invoke('create_structural_tension_chart', { desiredOutcome: 'Mastery of terminal agent workflows', currentReality: 'Basic CLI operations understood' }); ```

miadi-code: Three-Universe Tool Selection

```typescript // Engineer universe prefers certain tools const engineerTools = registry.listTools('domain:coding');

// Ceremony universe uses ceremonial tools const ceremonyTools = registry.listTools('ceremonial');

// Story Engine accesses narrative tools const storyTools = registry.listTools('narrative'); ```

jgt-code: Trading-Specific Toolset

```typescript const tradingTools = registry.listTools('domain:trading');

// Enforce direction ceremonies through tool invocation const signalResult = await registry.invoke('create_signal', { instrument: 'EURUSD', signalType: 'fdb_buy', williams: { ao_color: 'green', ac_color: 'green', ... } });

// Check obligations before execution const obligations = await registry.invoke('check_direction_obligations', { direction: 'north', campaignId: activeCampaign.id }); ```

VSCode Extension Integration

For VSCode-based agent environments:

```typescript // contribution point in package.json { "contributes": { "iaip.toolsets": [ { "id": "my-extension-tools", "configuration": "./toolsets.jsonc" } ] } }

// Extension activation export function activate(context: vscode.ExtensionContext) { const registry = getToolRegistry();

// Register custom tools registry.registerTool({ name: 'my_custom_tool', description: 'Extension-provided tool', invoke: async (input) => { /* ... */ } }); } ```

API Surface

```typescript export class ToolsetRegistry { // Initialization static create(config?: ToolsetConfig): ToolsetRegistry; static fromFile(path: string): ToolsetRegistry;

// Discovery listToolsets(): Toolset[]; listTools(filter?: ToolFilter): Tool[]; getTool(name: string): Tool | undefined; hasCapability(capability: string): boolean;

// Invocation invoke<T>(toolName: string, input: unknown): Promise<ToolResult<T>>; invokeWithConfirmation(toolName: string, input: unknown, confirm: ConfirmFn): Promise<ToolResult>;

// Registration registerTool(tool: ToolDefinition): void; registerToolset(toolset: ToolsetDefinition): void;

// MCP connectMCP(config: MCPServerConfig): Promise<void>; getMCPStatus(): MCPStatusReport;

// Events onToolsChanged(handler: () => void): Disposable; onMCPServerStatus(handler: (status: MCPStatus) => void): Disposable; }

interface ToolFilter { category?: string; registry?: string; modifiesState?: boolean; } ```

Success Criteria

āœ… toolsets.jsonc schema documented and validated āœ… ToolRegistry enables unified tool discovery across applications āœ… MCP servers bridged into registry seamlessly āœ… Category taxonomy supports domain-specific extensions āœ… VSCode extension contribution points defined āœ… Runtime hot-reload for development workflows āœ… Tool invocation includes confirmation for destructive operations

References

  • MCP Specification: https://modelcontextprotocol.io/
  • /a/src/coaia-narrative/ - MCP server implementation
  • /a/src/IAIP/prototypes/artefacts/stcmastery-vscode-what-is-toolset-*.md - Prior research