list_entities

Instructions

Implementation Reference

• pi/extensions/index.ts:270-296 (schema)

  Schema/type definition for the list_entities tool - defines its mcpName, label, description, promptSnippet, and parameters (concept, role, kind, top_k).

  {
    mcpName: "list_entities",
    label: "List Entities",
    description:
      "Find classes and functions matching a semantic role or concept. " +
      "Returns entities with semantic roles and concept tags.",
    promptSnippet:
      "ontomics_list_entities: find functions/classes by concept or role",
    parameters: Type.Object({
      concept: Type.Optional(
        Type.String({ description: "Filter by concept (e.g. 'loss')" }),
      ),
      role: Type.Optional(
        Type.String({
          description: "Filter by semantic role substring (e.g. 'module')",
        }),
      ),
      kind: Type.Optional(
        StringEnum(["class", "function"] as const, {
          description: "Filter by entity kind",
        }),
      ),
      top_k: Type.Optional(
        Type.Integer({ description: "Max entities to return (default: 20)" }),
      ),
    }),
  },

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

  Registration of the list_entities tool (along with all other tools) via pi.registerTool(), where the mcpName is prefixed with 'ontomics_' for the registered name.

  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)

  The execute handler for list_entities (and other tools). It calls the MCP client's callTool method with the mcpName and cleaned parameters, delegating the actual implementation to the external 'ontomics' binary via JSON-RPC 2.0 over stdio.

  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:352-360 (helper)

  The cleanArgs helper function used by the execute handler to strip undefined keys from parameters before forwarding to the MCP server.

  function cleanArgs(
    params: Record<string, unknown>,
  ): Record<string, unknown> {
    const out: Record<string, unknown> = {};
    for (const [k, v] of Object.entries(params)) {
      if (v !== undefined) out[k] = v;
    }
    return out;
  }