vocabulary_health

Instructions

Implementation Reference

• pi/extensions/index.ts:362-387 (registration)

  The tool 'vocabulary_health' is registered via pi.registerTool in a loop over toolDefs(). The registration wraps the mcpName 'vocabulary_health' into the prefixed name 'ontomics_vocabulary_health' and delegates execution to an external MCP subprocess (ontomics serve).

  for (const def of toolDefs()) {
    pi.registerTool({
      name: `ontomics_${def.mcpName}`,
      label: def.label,
      description: def.description,
      promptSnippet: def.promptSnippet,
      promptGuidelines: [
        "Use ontomics tools BEFORE grep/glob for semantic codebase questions.",
      ],
      parameters: def.parameters,
      async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
        onUpdate?.({
          content: [{ type: "text", text: `Querying ontomics: ${def.mcpName}...` }],
        });
        try {
          const mcp = await getClient();
          const text = await mcp.callTool(def.mcpName, cleanArgs(params));
          return { content: [{ type: "text", text }] };
        } catch (err) {
          throw new Error(
            `ontomics ${def.mcpName} failed: ${err instanceof Error ? err.message : String(err)}`,
          );
        }
      },
    });
  }

• pi/extensions/index.ts:297-306 (schema)

  Tool definition schema for 'vocabulary_health' within toolDefs(): mcpName: 'vocabulary_health', label: 'Vocabulary Health', description about convention coverage/consistency/cluster cohesion, and an empty parameters object (Type.Object({})).

  {
    mcpName: "vocabulary_health",
    label: "Vocabulary Health",
    description:
      "Measure vocabulary health — convention coverage, consistency ratio, " +
      "cluster cohesion, top inconsistencies.",
    promptSnippet:
      "ontomics_vocabulary_health: code quality metrics for naming consistency",
    parameters: Type.Object({}),
  },

• pi/extensions/index.ts:372-385 (handler)

  The execute handler for all ontomics tools (including vocabulary_health). It calls the external ontomics MCP server via McpClient.callTool with the tool's mcpName and cleaned parameters, returning the text result.

  async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
    onUpdate?.({
      content: [{ type: "text", text: `Querying ontomics: ${def.mcpName}...` }],
    });
    try {
      const mcp = await getClient();
      const text = await mcp.callTool(def.mcpName, cleanArgs(params));
      return { content: [{ type: "text", text }] };
    } catch (err) {
      throw new Error(
        `ontomics ${def.mcpName} failed: ${err instanceof Error ? err.message : String(err)}`,
      );
    }
  },

• pi/extensions/index.ts:13-98 (helper)

  McpClient class that communicates with the external 'ontomics serve' process over stdio JSON-RPC. The callTool method (line 44) is used by the handler to invoke the actual tool on the server side.

  class McpClient {
    private proc: ChildProcess;
    private rl: ReadlineInterface;
    private nextId = 1;
    private pending = new Map<
      number,
      { resolve: (v: unknown) => void; reject: (e: Error) => void }
    >();
  
    private constructor(proc: ChildProcess) {
      this.proc = proc;
      this.rl = createInterface({ input: proc.stdout! });
      this.rl.on("line", (line: string) => this.onLine(line));
      proc.stderr?.on("data", () => {});
    }
  
    static async start(binaryPath: string, cwd: string): Promise<McpClient> {
      const proc = spawn(binaryPath, ["serve"], {
        cwd,
        stdio: ["pipe", "pipe", "pipe"],
      });
      const client = new McpClient(proc);
      await client.request("initialize", {
        protocolVersion: "2024-11-05",
        capabilities: {},
        clientInfo: { name: "pi-ontomics", version: "1.0.0" },
      });
      client.notify("notifications/initialized", {});
      return client;
    }
  
    async callTool(
      name: string,
      args: Record<string, unknown>,
    ): Promise<string> {
      const result = (await this.request("tools/call", {
        name,
        arguments: args,
      })) as { content?: Array<{ text?: string }> };
      const text = result.content?.[0]?.text ?? JSON.stringify(result);
      return text;
    }
  
    dispose(): void {
      this.proc.kill();
      this.rl.close();
    }
  
    get alive(): boolean {
      return !this.proc.killed && this.proc.exitCode === null;
    }
  
    private request(method: string, params: unknown): Promise<unknown> {
      const id = this.nextId++;
      return new Promise((resolve, reject) => {
        this.pending.set(id, { resolve, reject });
        this.write({ jsonrpc: "2.0", id, method, params });
      });
    }
  
    private notify(method: string, params: unknown): void {
      this.write({ jsonrpc: "2.0", method, params });
    }
  
    private write(msg: unknown): void {
      this.proc.stdin!.write(JSON.stringify(msg) + "\n");
    }
  
    private onLine(line: string): void {
      if (!line.trim()) return;
      try {
        const msg = JSON.parse(line) as {
          id?: number;
          result?: unknown;
          error?: { message: string };
        };
        if (msg.id != null && this.pending.has(msg.id)) {
          const { resolve, reject } = this.pending.get(msg.id)!;
          this.pending.delete(msg.id);
          if (msg.error) reject(new Error(msg.error.message));
          else resolve(msg.result);
        }
      } catch {
        // ignore non-JSON lines (e.g. stderr leaks)
      }
    }