query_concept

Instructions

Implementation Reference

• pi/extensions/index.ts:134-163 (schema)

  Input schema for query_concept tool: defines parameters (term, max_related, max_occurrences, max_variants, max_signatures) with TypeBox validation.

  {
    mcpName: "query_concept",
    label: "Query Concept",
    description:
      "Semantic concept lookup — returns variants (including abbreviations), " +
      "related concepts, naming conventions, function signatures, and file locations.",
    promptSnippet:
      "ontomics_query_concept: semantic concept lookup with variants and relationships",
    parameters: Type.Object({
      term: Type.String({ description: "Concept term to look up" }),
      max_related: Type.Optional(
        Type.Integer({ description: "Max related concepts (default: 10)" }),
      ),
      max_occurrences: Type.Optional(
        Type.Integer({
          description: "Max occurrence locations (default: 5)",
        }),
      ),
      max_variants: Type.Optional(
        Type.Integer({
          description: "Max variant identifiers (default: 20)",
        }),
      ),
      max_signatures: Type.Optional(
        Type.Integer({
          description: "Max function signatures (default: 5)",
        }),
      ),
    }),
  },

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

  Registration loop that registers all tools including query_concept via pi.registerTool(). The actual execute handler delegates to the MCP client calling the ontomics binary.

  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:372-385 (handler)

  Execute handler for query_concept: delegates to ontomics MCP server via McpClient.callTool(), passing cleaned 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:44-54 (helper)

  McpClient.callTool() method that sends JSON-RPC request to the ontomics binary and extracts text response.

  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;
  }

• pi/extensions/index.ts:29-42 (helper)

  McpClient.start() static factory that spawns the ontomics binary and initializes the MCP connection.

  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;
  }