heptabase-cli.ts

#!/usr/bin/env bun
// @generated by mcporter@0.7.3 on 2026-02-21T07:28:46.447Z. DO NOT EDIT.
import { Command } from 'commander';
import { createRuntime, createServerProxy } from 'mcporter';
import { createCallResult } from 'mcporter';

const embeddedServer = {
  "name": "mcp-remote",
  "description": "Heptabase knowledge base CLI",
  "command": {
    "kind": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://api.heptabase.com/mcp",
      "--transport",
      "http-only"
    ]
  },
  "source": {
    "kind": "local",
    "path": "<adhoc>"
  }
} as const;
const embeddedSchemas = {
  "save_to_note_card": {
    "type": "object",
    "properties": {
      "content": {
        "type": "string",
        "description": "Content of the card. In markdown format. Each block should be separated by an empty line. The first line should be an h1, which will be treated as the title of the card."
      }
    },
    "required": [
      "content"
    ],
    "additionalProperties": false
  },
  "append_to_journal": {
    "type": "object",
    "properties": {
      "content": {
        "type": "string",
        "description": "Content to append to the journal. In markdown format. Each block should be separated by an empty line."
      }
    },
    "required": [
      "content"
    ],
    "additionalProperties": false
  },
  "get_journal_range": {
    "type": "object",
    "properties": {
      "startDate": {
        "type": "string",
        "description": "The start date of the journal range (YYYY-MM-DD). Maximum 92 days between startDate and endDate."
      },
      "endDate": {
        "type": "string",
        "description": "The end date of the journal range (YYYY-MM-DD). Must be >= startDate and within 92 days of startDate."
      }
    },
    "required": [
      "startDate",
      "endDate"
    ],
    "additionalProperties": false
  },
  "get_whiteboard_with_objects": {
    "type": "object",
    "properties": {
      "whiteboardId": {
        "type": "string",
        "description": "The id of the whiteboard to retrieve with all its objects."
      }
    },
    "required": [
      "whiteboardId"
    ],
    "additionalProperties": false
  },
  "get_object": {
    "type": "object",
    "properties": {
      "objectId": {
        "type": "string",
        "description": "The id of the object to retrieve."
      },
      "objectType": {
        "type": "string",
        "enum": [
          "card",
          "journal",
          "videoCard",
          "audioCard",
          "imageCard",
          "highlightElement",
          "textElement",
          "videoElement",
          "imageElement",
          "chat",
          "chatMessage",
          "chatMessagesElement",
          "section"
        ],
        "description": "The type of the object. Do not use it on pdfCard."
      }
    },
    "required": [
      "objectId",
      "objectType"
    ],
    "additionalProperties": false
  },
  "get_pdf_pages": {
    "type": "object",
    "properties": {
      "pdfCardId": {
        "type": "string",
        "description": "The UUID of the PDF card to get pages from."
      },
      "startPageNumber": {
        "type": "integer",
        "description": "The page number to start from. (inclusive, starts from 1)"
      },
      "endPageNumber": {
        "type": "integer",
        "description": "The page number to end at. (inclusive)"
      }
    },
    "required": [
      "pdfCardId",
      "startPageNumber",
      "endPageNumber"
    ],
    "additionalProperties": false
  },
  "search_pdf_content": {
    "type": "object",
    "properties": {
      "pdfCardId": {
        "type": "string",
        "description": "The UUID of the PDF card to search."
      },
      "keywords": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1,
        "maxItems": 5,
        "description": "No more than 5 keywords. Use varied terms, synonyms, and related concepts (e.g., [\"neural network\", \"deep learning\", \"architecture\"]). OR logic—diverse keywords = broader coverage."
      }
    },
    "required": [
      "pdfCardId",
      "keywords"
    ],
    "additionalProperties": false
  },
  "semantic_search_objects": {
    "type": "object",
    "properties": {
      "queries": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1,
        "maxItems": 3,
        "description": "Array of search queries in natural language (1-3 queries). Multiple queries from different perspectives improve coverage. Example: [\"climate change impacts\", \"environmental policy\"]."
      },
      "resultObjectTypes": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "card",
            "pdfCard",
            "mediaCard",
            "highlightElement",
            "journal"
          ]
        },
        "minItems": 0,
        "description": "Filter for specific object types. Pass empty array to search all types."
      }
    },
    "required": [
      "queries",
      "resultObjectTypes"
    ],
    "additionalProperties": false
  },
  "search_whiteboards": {
    "type": "object",
    "properties": {
      "keywords": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1,
        "maxItems": 5,
        "description": "1-5 keywords. Use varied terms, synonyms, and related concepts for broader coverage (OR logic). Example: [\"project management\", \"productivity\", \"workflow\"]."
      }
    },
    "required": [
      "keywords"
    ],
    "additionalProperties": false
  }
} as const;
const embeddedName = "mcp-remote";
const embeddedDescription = "Heptabase knowledge base CLI";
const generatorInfo = "Generated by mcporter@0.7.3 — https://github.com/steipete/mcporter";
const generatorTools = [
  {
    "name": "save-to-note-card",
    "description": "Save any information to a note card in the main space in Heptabase.",
    "usage": "save-to-note-card --content <content> [--raw <json>]",
    "flags": "--content <content> [--raw <json>]"
  },
  {
    "name": "append-to-journal",
    "description": "Append content to today's journal in Heptabase. If today's journal does not exist, it will be created.",
    "usage": "append-to-journal --content <content> [--raw <json>]",
    "flags": "--content <content> [--raw <json>]"
  },
  {
    "name": "get-journal-range",
    "description": "Retrieve daily journal entries within a date range (inclusive) from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Complete content for each journal entry in the specified period\n- All journal entries from startDate to endDate (inclusive)\n\nUSE WHEN:\n- User asks about their journal entries during a time period\n- User wants to see what they wrote in past days/weeks/months\n- User needs to review their daily notes\n\nIMPORTANT CONSTRAINTS:\n- Each call can retrieve at most 92 days (approximately 3 months)\n- For longer periods, make multiple calls (e.g., 4 calls for one year)\n- Dates use YYYY-MM-DD format. Both startDate and endDate are inclusive.",
    "usage": "get-journal-range --start-date <start-date> --end-date <end-date> [--raw <json>]",
    "flags": "--start-date <start-date> --end-date <end-date> [--raw <json>]"
  },
  {
    "name": "get-whiteboard-with-objects",
    "description": "List all objects on a whiteboard with their content from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Complete whiteboard structure showing all objects and their relationships\n- Partial content of cards, sections, text elements, mindmaps, images on the whiteboard\n- Connections between objects\n\nUSE WHEN:\n- You've already got the whiteboard id from searchWhiteboards or semanticSearchObjects\n\nHEPTABASE STRUCTURE:\n- Whiteboards are visual canvases containing multiple objects\n- Objects on the same whiteboard are typically related to the same topic",
    "usage": "get-whiteboard-with-objects --whiteboard-id <whiteboard-id> [--raw <json>]",
    "flags": "--whiteboard-id <whiteboard-id> [--raw <json>]"
  },
  {
    "name": "get-object",
    "description": "Retrieve the complete content of an object from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Full content of cards (notes, journals, media, highlights)\n- Complete transcripts for video/audio cards\n- All content regardless of length (no chunk limits)\n\nUSE WHEN:\n- You found relevant objects via semanticSearchObjects or getWhiteboardWithObjects and need full content\n  - Determine if you have all the content of an object by checking its \"hasMore\" flag\n- User asks about a specific object you've identified\n- You need complete information (e.g., for summarization, translation, or detailed questions)\n\nOBJECT TYPES:\n- card: Text notes\n- videoCard/audioCard/imageCard\n- journal: Daily journal entries  \n- highlightElement\n- section/textElement: whiteboard elements\n- chat/chatMessage/chatMessagesElement: Chat conversations\n\nNOTE: Do not use this on pdfCard objects since they might be too large.",
    "usage": "get-object --object-id <object-id> --object-type <object-type:card|journal|videoCard|audioCard|imageCard|highlightElement|textElement|videoElement|imageElement|chat|chatMessage|chatMessagesElement|section> [--raw <json>]",
    "flags": "--object-id <object-id> --object-type <object-type:card|journal|videoCard|audioCard|imageCard|highlightElement|textElement|videoElement|imageElement|chat|chatMessage|chatMessagesElement|section> [--raw <json>]"
  },
  {
    "name": "get-pdf-pages",
    "description": "Retrieve specific pages from a PDF card by page numbers from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Complete content from [startPageNumber, endPageNumber] inclusive\n- All content from the specified page range\n\nUSE WHEN:\n- You know the specific page numbers to retrieve\n- User asks for content from specific pages\n- You need complete sections after finding relevant pages via search_pdf_content\n- For summarization/translation, retrieve pages in batches\n\nNOTE: Page numbers start from 1 (not 0). You can get any number of pages you want. But if you need significantly more than 100 pages, ask user for clarification first.",
    "usage": "get-pdf-pages --pdf-card-id <pdf-card-id> --start-page-number <start-page-number:number> --end-page-number <end-page-number:number> [--raw <json>]",
    "flags": "--pdf-card-id <pdf-card-id> --start-page-number <start-page-number:number> --end-page-number <end-page-number:number> [--raw <json>]"
  },
  {
    "name": "search-pdf-content",
    "description": "Search within a large PDF using BM25 keyword matching (OR logic, fuzzy) from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Up to 80 ranked chunks matching the keywords\n- Expanded contiguous ranges around matching chunks for context\n\nUSE WHEN:\n- User asks about content within a PDF\n- You need to find specific information in a PDF document\n- User wants to search for keywords or topics in a PDF\n\nIMPORTANT:\n- You must first obtain the PDF card ID using other available tools (e.g., semanticSearchObjects or getObject) before calling this function\n- Use broad keywords, synonyms, and related terms to maximize coverage\n- Follow with get_pdf_pages for complete sections if needed",
    "usage": "search-pdf-content --pdf-card-id <pdf-card-id> --keywords <keywords:value1,value2> [--raw <json>]",
    "flags": "--pdf-card-id <pdf-card-id> --keywords <keywords:value1,value2> [--raw <json>]"
  },
  {
    "name": "semantic-search-objects",
    "description": "Find WHICH objects exist on a topic in the user's Heptabase knowledge base using hybrid search (full-text + semantic).\n\nHEPTABASE STRUCTURE:\n- Cards: Knowledge units (notes, journals, PDFs, videos, images, highlights)\n- Whiteboards: Visual canvases containing cards and other objects\n\nUSE WHEN: Discovering what content exists about a topic (e.g., \"machine learning papers\", \"project notes\")\n\nSTRATEGY:\n- Use multiple queries from different perspectives (1-3 queries)\n- Results show previews with titles and partial content\n- If you find relevant objects, use getObject to retrieve complete content\n- Returned objects may reference whiteboards they're on—use searchWhiteboards if you need to explore those whiteboards",
    "usage": "semantic-search-objects --queries <queries:value1,value2> --result-object-types <result-object-types:card|pdfCard|mediaCard|highlightElement|journal> [--raw <json>]",
    "flags": "--queries <queries:value1,value2> --result-object-types <result-object-types:card|pdfCard|mediaCard|highlightElement|journal> [--raw <json>]"
  },
  {
    "name": "search-whiteboards",
    "description": "Search for whiteboards by keywords in the user's Heptabase knowledge base.\n\nHEPTABASE STRUCTURE:\n- Whiteboards are visual canvases where users organize their knowledge\n- Each whiteboard contains cards, sections, text elements, mindmaps, images, and connections\n- Users typically group related content on the same whiteboard\n- Whiteboard names/titles indicate their topic or purpose\n\nUSE WHEN:\n- Looking for whiteboards on a specific topic (e.g., \"machine learning project\", \"research papers\")\n- User mentions exploring or understanding their workspace organization\n- You found objects via semanticSearchObjects that reference interesting whiteboards\n- Need to see how content is organized and connected\n\nSEARCH STRATEGY:\n- Use varied keywords, synonyms, and related concepts for better coverage\n- OR logic: diverse keywords = broader results\n- Example: [\"neural network\", \"deep learning\", \"architecture\"]\n\nNEXT STEPS:\n- Results show whiteboard titles and basic info\n- Use getWhiteboardWithObjects to retrieve full content of relevant whiteboards",
    "usage": "search-whiteboards --keywords <keywords:value1,value2> [--raw <json>]",
    "flags": "--keywords <keywords:value1,value2> [--raw <json>]"
  }
] as const;
const embeddedMetadata = {
  "schemaVersion": 1,
  "generatedAt": "2026-02-21T07:28:46.447Z",
  "generator": {
    "name": "mcporter",
    "version": "0.7.3"
  },
  "server": {
    "name": "mcp-remote",
    "source": {
      "kind": "local",
      "path": "<adhoc>"
    },
    "definition": {
      "name": "mcp-remote",
      "description": "Heptabase knowledge base CLI",
      "command": {
        "kind": "stdio",
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote@latest",
          "https://api.heptabase.com/mcp",
          "--transport",
          "http-only"
        ]
      }
    }
  },
  "artifact": {
    "path": "",
    "kind": "template"
  },
  "invocation": {
    "serverRef": "{\"name\":\"mcp-remote\",\"description\":\"Heptabase knowledge base CLI\",\"command\":{\"kind\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"mcp-remote@latest\",\"https://api.heptabase.com/mcp\",\"--transport\",\"http-only\"]},\"source\":{\"kind\":\"local\",\"path\":\"<adhoc>\"}}",
    "configPath": "<adhoc>",
    "runtime": "bun",
    "bundler": "bun",
    "outputPath": "./heptabase-cli.ts",
    "compile": "./heptabase",
    "timeoutMs": 30000,
    "minify": false
  }
} as const;
const artifactKind = determineArtifactKind();
const program = new Command();
program.name(embeddedName);
program.description(embeddedDescription);
program.option('-t, --timeout <ms>', 'Call timeout in milliseconds', (value) => parseInt(value, 10), 30000);
program.option('-o, --output <format>', 'Output format: text|markdown|json|raw', 'text');
const commandSignatures: Record<string, string> = {
  "save-to-note-card": "function save_to_note_card(content: string);",
  "append-to-journal": "function append_to_journal(content: string);",
  "get-journal-range": "function get_journal_range(startDate: string, endDate: string);",
  "get-whiteboard-with-objects": "function get_whiteboard_with_objects(whiteboardId: string);",
  "get-object": "function get_object(objectId: string, objectType: \"card\" | \"journal\" | \"videoCard\" | \"audioCard\" | \"imageCard\" | \"highlightElement\" | \"textElement\" | \"videoElement\" | \"imageElement\" | \"chat\" | \"chatMessage\" | \"chatMessagesElement\" | \"section\");",
  "get-pdf-pages": "function get_pdf_pages(pdfCardId: string, startPageNumber: number, endPageNumber: number);",
  "search-pdf-content": "function search_pdf_content(pdfCardId: string, keywords: string[]);",
  "semantic-search-objects": "function semantic_search_objects(queries: string[], resultObjectTypes: \"card\" | \"pdfCard\" | \"mediaCard\" | \"highlightElement\" | \"journal\");",
  "search-whiteboards": "function search_whiteboards(keywords: string[]);"
};
program.configureHelp({
	commandTerm(cmd) {
		const term = cmd.name();
		return commandSignatures[term] ?? cmd.name();
	},
});
program.showSuggestionAfterError(true);

program
	.command("save-to-note-card")
	.summary("save-to-note-card --content <content> [--raw <json>]")
	.description("Save any information to a note card in the main space in Heptabase.")
	.usage("--content <content> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--content <content>", "Content of the card. In markdown format. Each block should be separated by an empty line. The first line should be an h1, which will be treated as the title of the card.")
	
	.alias("save_to_note_card")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.content !== undefined) args.content = cmdOpts.content;
			const call = (proxy.saveToNoteCard as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.save_to_note_card(content: \"value\")");

program
	.command("append-to-journal")
	.summary("append-to-journal --content <content> [--raw <json>]")
	.description("Append content to today's journal in Heptabase. If today's journal does not exist, it will be created.")
	.usage("--content <content> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--content <content>", "Content to append to the journal. In markdown format. Each block should be separated by an empty line.")
	
	.alias("append_to_journal")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.content !== undefined) args.content = cmdOpts.content;
			const call = (proxy.appendToJournal as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.append_to_journal(content: \"value\")");

program
	.command("get-journal-range")
	.summary("get-journal-range --start-date <start-date> --end-date <end-date> [--raw <json>]")
	.description("Retrieve daily journal entries within a date range (inclusive) from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Complete content for each journal entry in the specified period\n- All journal entries from startDate to endDate (inclusive)\n\nUSE WHEN:\n- User asks about their journal entries during a time period\n- User wants to see what they wrote in past days/weeks/months\n- User needs to review their daily notes\n\nIMPORTANT CONSTRAINTS:\n- Each call can retrieve at most 92 days (approximately 3 months)\n- For longer periods, make multiple calls (e.g., 4 calls for one year)\n- Dates use YYYY-MM-DD format. Both startDate and endDate are inclusive.")
	.usage("--start-date <start-date> --end-date <end-date> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--start-date <start-date>", "The start date of the journal range (YYYY-MM-DD). Maximum 92 days between startDate and endDate.")
	.requiredOption("--end-date <end-date>", "The end date of the journal range (YYYY-MM-DD). Must be >= startDate and within 92 days of startDate.")
	
	.alias("get_journal_range")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.startDate !== undefined) args.startDate = cmdOpts.startDate;
		if (cmdOpts.endDate !== undefined) args.endDate = cmdOpts.endDate;
			const call = (proxy.getJournalRange as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.get_journal_range(startDate: \"value\", endDate: \"value\")");

program
	.command("get-whiteboard-with-objects")
	.summary("get-whiteboard-with-objects --whiteboard-id <whiteboard-id> [--raw <json>]")
	.description("List all objects on a whiteboard with their content from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Complete whiteboard structure showing all objects and their relationships\n- Partial content of cards, sections, text elements, mindmaps, images on the whiteboard\n- Connections between objects\n\nUSE WHEN:\n- You've already got the whiteboard id from searchWhiteboards or semanticSearchObjects\n\nHEPTABASE STRUCTURE:\n- Whiteboards are visual canvases containing multiple objects\n- Objects on the same whiteboard are typically related to the same topic")
	.usage("--whiteboard-id <whiteboard-id> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--whiteboard-id <whiteboard-id>", "The id of the whiteboard to retrieve with all its objects. (example: example-id)")
	
	.alias("get_whiteboard_with_objects")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.whiteboardId !== undefined) args.whiteboardId = cmdOpts.whiteboardId;
			const call = (proxy.getWhiteboardWithObjects as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.get_whiteboard_with_objects(whiteboardId: \"example-id\")");

program
	.command("get-object")
	.summary("get-object --object-id <object-id> --object-type <object-type:card|journal|videoCard|audioCard|imageCard|highlightElement|textElement|videoElement|imageElement|chat|chatMessage|chatMessagesElement|section> [--raw <json>]")
	.description("Retrieve the complete content of an object from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Full content of cards (notes, journals, media, highlights)\n- Complete transcripts for video/audio cards\n- All content regardless of length (no chunk limits)\n\nUSE WHEN:\n- You found relevant objects via semanticSearchObjects or getWhiteboardWithObjects and need full content\n  - Determine if you have all the content of an object by checking its \"hasMore\" flag\n- User asks about a specific object you've identified\n- You need complete information (e.g., for summarization, translation, or detailed questions)\n\nOBJECT TYPES:\n- card: Text notes\n- videoCard/audioCard/imageCard\n- journal: Daily journal entries  \n- highlightElement\n- section/textElement: whiteboard elements\n- chat/chatMessage/chatMessagesElement: Chat conversations\n\nNOTE: Do not use this on pdfCard objects since they might be too large.")
	.usage("--object-id <object-id> --object-type <object-type:card|journal|videoCard|audioCard|imageCard|highlightElement|textElement|videoElement|imageElement|chat|chatMessage|chatMessagesElement|section> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--object-id <object-id>", "The id of the object to retrieve. (example: example-id)")
	.requiredOption("--object-type <object-type:card|journal|videoCard|audioCard|imageCard|highlightElement|textElement|videoElement|imageElement|chat|chatMessage|chatMessagesElement|section>", "The type of the object. Do not use it on pdfCard. (choices: card, journal, videoCard, audioCard, imageCard, highlightElement, textElement, videoElement, imageElement, chat, chatMessage, chatMessagesElement, section; example: card)")
	
	.alias("get_object")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.objectId !== undefined) args.objectId = cmdOpts.objectId;
		if (cmdOpts.objectType !== undefined) args.objectType = cmdOpts.objectType;
			const call = (proxy.getObject as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.get_object(objectId: \"example-id\", objectType: \"card\")");

program
	.command("get-pdf-pages")
	.summary("get-pdf-pages --pdf-card-id <pdf-card-id> --start-page-number <start-page-number:number> --end-page-number <end-page-number:number> [--raw <json>]")
	.description("Retrieve specific pages from a PDF card by page numbers from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Complete content from [startPageNumber, endPageNumber] inclusive\n- All content from the specified page range\n\nUSE WHEN:\n- You know the specific page numbers to retrieve\n- User asks for content from specific pages\n- You need complete sections after finding relevant pages via search_pdf_content\n- For summarization/translation, retrieve pages in batches\n\nNOTE: Page numbers start from 1 (not 0). You can get any number of pages you want. But if you need significantly more than 100 pages, ask user for clarification first.")
	.usage("--pdf-card-id <pdf-card-id> --start-page-number <start-page-number:number> --end-page-number <end-page-number:number> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--pdf-card-id <pdf-card-id>", "The UUID of the PDF card to get pages from. (example: example-id)")
	.requiredOption("--start-page-number <start-page-number:number>", "The page number to start from. (inclusive, starts from 1) (example: 1)", (value) => parseFloat(value))
	.requiredOption("--end-page-number <end-page-number:number>", "The page number to end at. (inclusive) (example: 1)", (value) => parseFloat(value))
	
	.alias("get_pdf_pages")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.pdfCardId !== undefined) args.pdfCardId = cmdOpts.pdfCardId;
		if (cmdOpts.startPageNumber !== undefined) args.startPageNumber = cmdOpts.startPageNumber;
		if (cmdOpts.endPageNumber !== undefined) args.endPageNumber = cmdOpts.endPageNumber;
			const call = (proxy.getPdfPages as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.get_pdf_pages(pdfCardId: \"example-id\", startPageN, ...)");

program
	.command("search-pdf-content")
	.summary("search-pdf-content --pdf-card-id <pdf-card-id> --keywords <keywords:value1,value2> [--raw <json>]")
	.description("Search within a large PDF using BM25 keyword matching (OR logic, fuzzy) from the user's Heptabase knowledge base.\n\nWHAT IT RETURNS:\n- Up to 80 ranked chunks matching the keywords\n- Expanded contiguous ranges around matching chunks for context\n\nUSE WHEN:\n- User asks about content within a PDF\n- You need to find specific information in a PDF document\n- User wants to search for keywords or topics in a PDF\n\nIMPORTANT:\n- You must first obtain the PDF card ID using other available tools (e.g., semanticSearchObjects or getObject) before calling this function\n- Use broad keywords, synonyms, and related terms to maximize coverage\n- Follow with get_pdf_pages for complete sections if needed")
	.usage("--pdf-card-id <pdf-card-id> --keywords <keywords:value1,value2> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--pdf-card-id <pdf-card-id>", "The UUID of the PDF card to search. (example: example-id)")
	.requiredOption("--keywords <keywords:value1,value2>", "No more than 5 keywords. Use varied terms, synonyms, and related concepts (e.g., [\"neural network\", \"deep learning\", \"architecture\"]). OR logic—diverse keywords = broader coverage. (example: value1,value2)", (value) => value.split(',').map((v) => v.trim()))
	
	.alias("search_pdf_content")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.pdfCardId !== undefined) args.pdfCardId = cmdOpts.pdfCardId;
		if (cmdOpts.keywords !== undefined) args.keywords = cmdOpts.keywords;
			const call = (proxy.searchPdfContent as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.search_pdf_content(pdfCardId: \"example-id\", keywo, ...)");

program
	.command("semantic-search-objects")
	.summary("semantic-search-objects --queries <queries:value1,value2> --result-object-types <result-object-types:card|pdfCard|mediaCard|highlightElement|journal> [--raw <json>]")
	.description("Find WHICH objects exist on a topic in the user's Heptabase knowledge base using hybrid search (full-text + semantic).\n\nHEPTABASE STRUCTURE:\n- Cards: Knowledge units (notes, journals, PDFs, videos, images, highlights)\n- Whiteboards: Visual canvases containing cards and other objects\n\nUSE WHEN: Discovering what content exists about a topic (e.g., \"machine learning papers\", \"project notes\")\n\nSTRATEGY:\n- Use multiple queries from different perspectives (1-3 queries)\n- Results show previews with titles and partial content\n- If you find relevant objects, use getObject to retrieve complete content\n- Returned objects may reference whiteboards they're on—use searchWhiteboards if you need to explore those whiteboards")
	.usage("--queries <queries:value1,value2> --result-object-types <result-object-types:card|pdfCard|mediaCard|highlightElement|journal> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--queries <queries:value1,value2>", "Array of search queries in natural language (1-3 queries). Multiple queries from different perspectives improve coverage. Example: [\"climate change impacts\", \"environmental policy\"]. (example: value1,value2)", (value) => value.split(',').map((v) => v.trim()))
	.requiredOption("--result-object-types <result-object-types:card|pdfCard|mediaCard|highlightElement|journal>", "Filter for specific object types. Pass empty array to search all types. (choices: card, pdfCard, mediaCard, highlightElement, journal; example: card)", (value) => value.split(',').map((v) => v.trim()))
	
	.alias("semantic_search_objects")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.queries !== undefined) args.queries = cmdOpts.queries;
		if (cmdOpts.resultObjectTypes !== undefined) args.resultObjectTypes = cmdOpts.resultObjectTypes;
			const call = (proxy.semanticSearchObjects as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.semantic_search_objects(queries: [\"value1\", \"valu, ...)");

program
	.command("search-whiteboards")
	.summary("search-whiteboards --keywords <keywords:value1,value2> [--raw <json>]")
	.description("Search for whiteboards by keywords in the user's Heptabase knowledge base.\n\nHEPTABASE STRUCTURE:\n- Whiteboards are visual canvases where users organize their knowledge\n- Each whiteboard contains cards, sections, text elements, mindmaps, images, and connections\n- Users typically group related content on the same whiteboard\n- Whiteboard names/titles indicate their topic or purpose\n\nUSE WHEN:\n- Looking for whiteboards on a specific topic (e.g., \"machine learning project\", \"research papers\")\n- User mentions exploring or understanding their workspace organization\n- You found objects via semanticSearchObjects that reference interesting whiteboards\n- Need to see how content is organized and connected\n\nSEARCH STRATEGY:\n- Use varied keywords, synonyms, and related concepts for better coverage\n- OR logic: diverse keywords = broader results\n- Example: [\"neural network\", \"deep learning\", \"architecture\"]\n\nNEXT STEPS:\n- Results show whiteboard titles and basic info\n- Use getWhiteboardWithObjects to retrieve full content of relevant whiteboards")
	.usage("--keywords <keywords:value1,value2> [--raw <json>]")
	.option('--raw <json>', 'Provide raw JSON arguments to the tool, bypassing flag parsing.')

	.requiredOption("--keywords <keywords:value1,value2>", "1-5 keywords. Use varied terms, synonyms, and related concepts for broader coverage (OR logic). Example: [\"project management\", \"productivity\", \"workflow\"]. (example: value1,value2)", (value) => value.split(',').map((v) => v.trim()))
	
	.alias("search_whiteboards")	.action(async (cmdOpts) => {
		const globalOptions = program.opts();
		const runtime = await ensureRuntime();
		const serverName = embeddedName;
		const proxy = createServerProxy(runtime, serverName, {
			initialSchemas: embeddedSchemas,
		});
		try {
			const args = cmdOpts.raw ? JSON.parse(cmdOpts.raw) : ({} as Record<string, unknown>);
			if (cmdOpts.keywords !== undefined) args.keywords = cmdOpts.keywords;
			const call = (proxy.searchWhiteboards as any)(args);
			const result = await invokeWithTimeout(call, globalOptions.timeout || 30000);
			printResult(result, globalOptions.output ?? 'text');
		} finally {
			await runtime.close(serverName).catch(() => {});
		}
	})
	.addHelpText('after', () => '\nExample:\n  ' + "mcporter call mcp-remote.search_whiteboards(keywords: [\"value1\", \"value2\"])");

program
	.command('__mcporter_inspect', { hidden: true })
	.description('Internal metadata printer for mcporter inspect-cli.')
	.action(() => {
		const payload = buildMetadataPayload();
		console.log(JSON.stringify(payload, null, 2));
	});

configureToolCommandHelps();

const FORCE_COLOR = process.env.FORCE_COLOR?.toLowerCase();
const forceDisableColor = FORCE_COLOR === '0' || FORCE_COLOR === 'false';
const forceEnableColor = FORCE_COLOR === '1' || FORCE_COLOR === 'true' || FORCE_COLOR === '2' || FORCE_COLOR === '3';
const hasNoColor = process.env.NO_COLOR !== undefined;
const stdoutStream = process.stdout as NodeJS.WriteStream | undefined;
const supportsAnsiColor = !hasNoColor && (forceEnableColor || (!forceDisableColor && Boolean(stdoutStream?.isTTY)));

const tint = {
	bold(text: string): string {
		return supportsAnsiColor ? '' + text + '' : text;
	},
	dim(text: string): string {
		return supportsAnsiColor ? '' + text + '' : text;
	},
	extraDim(text: string): string {
		return supportsAnsiColor ? '' + text + '' : text;
	},
};

function configureGeneratedCommandHelp(command: Command): void {
	command.configureHelp({
		commandUsage(target) {
			const usage = (target.name() + ' ' + target.usage()).trim() || target.name();
			return supportsAnsiColor ? tint.bold(usage) : usage;
		},
		optionTerm(option) {
			const term = option.flags ?? '';
			return supportsAnsiColor ? tint.bold(term) : term;
		},
		optionDescription(option) {
			const description = option.description ?? '';
			return supportsAnsiColor ? tint.extraDim(description) : description;
		},
	});
}

function configureToolCommandHelps(): void {
	program.commands.forEach((cmd) => {
		if (cmd.name() === '__mcporter_inspect') {
			return;
		}
		configureGeneratedCommandHelp(cmd);
	});
}

function renderStandaloneHelp(): string {
	const colorfulTitle = tint.bold(embeddedName) + ' ' + tint.dim('— ' + embeddedDescription);
	const plainTitle = embeddedName + ' — ' + embeddedDescription;
	const title = supportsAnsiColor ? colorfulTitle : plainTitle;
	const lines = [title, '', 'Usage: ' + embeddedName + ' <command> [options]', ''];
	if (generatorTools) {
		lines.push(formatEmbeddedTools());
	}
	lines.push('', formatGlobalFlags(), '', formatQuickStart());
	if (generatorInfo) {
		lines.push('', tint.extraDim(generatorInfo));
	}
	return lines.join('\n');
}

program.helpInformation = () => renderStandaloneHelp();

function formatEmbeddedTools(): string {
	const header = supportsAnsiColor ? tint.bold('Embedded tools') : 'Embedded tools';
	if (!generatorTools.length) {
		return header;
	}
	const lines = [header];
	generatorTools.forEach((entry) => {
		const renderedDesc = entry.description
			? supportsAnsiColor
				? tint.extraDim(entry.description)
				: entry.description
			: undefined;
		const base = renderedDesc ? entry.name + ' - ' + renderedDesc : entry.name;
		lines.push('  ' + base);
		if (entry.flags) {
			const renderedFlags = supportsAnsiColor ? tint.extraDim(entry.flags) : entry.flags;
			lines.push('    ' + renderedFlags);
		}
		lines.push('');
	});
	if (lines[lines.length - 1] === '') {
		lines.pop();
	}
	return lines.join('\n');
}

function formatGlobalFlags(): string {
	const header = supportsAnsiColor ? tint.bold('Global flags') : 'Global flags';
	const entries = [
		['-t, --timeout <ms>', 'Call timeout in milliseconds'],
		['-o, --output <format>', 'text | markdown | json | raw (default text)'],
	];
	const formatted = entries.map(([flag, summary]) => '  ' + flag.padEnd(28) + summary);
	return [header, ...formatted].join('\n');
}

function formatQuickStart(): string {
  const header = supportsAnsiColor ? tint.bold('Quick start') : 'Quick start';
  const examples = quickStartExamples();
  if (!examples.length) {
    return header;
  }
  const formatted = examples.map(([cmd, note]) => '  ' + cmd + '\n    ' + tint.dim('# ' + note));
  return [header, ...formatted].join('\n');
}

function quickStartExamples(): Array<[string, string]> {
  const examples: Array<[string, string]> = [];
  const commandMap = new Map<string, string>();
  program.commands.forEach((cmd) => {
    const name = cmd.name();
    if (name !== '__mcporter_inspect') {
      commandMap.set(name, name);
    }
  });
  const embedded = Array.isArray(generatorTools) ? generatorTools : [];
  for (const entry of embedded.slice(0, 3)) {
    const commandName = commandMap.get(entry.name) ?? entry.name;
    const flags = entry.flags ? ' ' + entry.flags.replace(/<[^>]+>/g, '<value>') : '';
    examples.push([embeddedName + ' ' + commandName + flags, 'invoke ' + commandName]);
  }
  if (!examples.length) {
    examples.push([embeddedName + ' <tool> --key value', 'invoke a tool with flags']);
  }
  return examples;
}

function printResult(result: unknown, format: string) {
	const wrapped = createCallResult(result);
	switch (format) {
		case 'json': {
			const json = wrapped.json();
			if (json) {
				console.log(JSON.stringify(json, null, 2));
				return;
			}
			break;
		}
		case 'markdown': {
			const markdown = wrapped.markdown();
			if (markdown) {
				console.log(markdown);
				return;
			}
			break;
		}
		case 'raw': {
			console.log(JSON.stringify(wrapped.raw, null, 2));
			return;
		}
	}
	const text = wrapped.text();
	if (text) {
		console.log(text);
	} else {
		console.log(JSON.stringify(wrapped.raw, null, 2));
	}
}

function normalizeEmbeddedServer(server: typeof embeddedServer) {
	const base = { ...server } as Record<string, unknown>;
	if ((server.command as any).kind === 'http') {
		const urlRaw = (server.command as any).url;
		const urlValue = typeof urlRaw === 'string' ? urlRaw : String(urlRaw);
		return {
			...base,
			command: {
				...(server.command as Record<string, unknown>),
				url: new URL(urlValue),
			},
		};
	}
	if ((server.command as any).kind === 'stdio') {
		return {
			...base,
			command: {
				...(server.command as Record<string, unknown>),
				args: [ ...((server.command as any).args ?? []) ],
			},
		};
	}
	return base;
}

function determineArtifactKind(): 'template' | 'bundle' | 'binary' {
	const scriptPath = typeof process !== 'undefined' && Array.isArray(process.argv) ? process.argv[1] ?? '' : '';
	if (scriptPath.endsWith('.ts')) {
		return 'template';
	}
	if (scriptPath.endsWith('.js')) {
		return 'bundle';
	}
	return 'binary';
}

function resolveArtifactPath(): string {
	if (typeof process !== 'undefined' && Array.isArray(process.argv) && process.argv.length > 1) {
		const script = process.argv[1];
		if (script) {
			return script;
		}
	}
	return embeddedMetadata.artifact.path;
}

function buildMetadataPayload() {
	const invocation = { ...embeddedMetadata.invocation };
	const path = resolveArtifactPath();
	if (artifactKind === 'template' && path) {
		invocation.outputPath = invocation.outputPath ?? path;
	} else if (artifactKind === 'bundle' && path) {
		invocation.bundle = invocation.bundle ?? path;
	} else if (artifactKind === 'binary' && path) {
		invocation.compile = invocation.compile ?? path;
	}
	return {
		...embeddedMetadata,
		artifact: {
			path,
			kind: artifactKind,
		},
		invocation,
	};
}

async function ensureRuntime(): Promise<Awaited<ReturnType<typeof createRuntime>>> {
	return await createRuntime({
		servers: [normalizeEmbeddedServer(embeddedServer)],
	});
}

async function invokeWithTimeout<T>(call: Promise<T>, timeout: number): Promise<T> {
	if (!Number.isFinite(timeout) || timeout <= 0) {
		return await call;
	}
	let timer: ReturnType<typeof setTimeout> | undefined;
	try {
		return await Promise.race([
			call,
			new Promise<never>((_, reject) => {
				timer = setTimeout(() => {
					reject(new Error('Call timed out after ' + timeout + 'ms.'));
				}, timeout);
			}),
		]);
	} finally {
		if (timer) {
			clearTimeout(timer);
		}
	}
}

async function runCli(): Promise<void> {
	const args = process.argv.slice(2);
	if (args.length === 0) {
		program.outputHelp();
		return;
	}
	await program.parseAsync(process.argv);
}

if (process.env.MCPORTER_DISABLE_AUTORUN !== '1') {
	runCli().catch((error) => {
		const message = error instanceof Error ? error.message : String(error);
		console.error(message);
		process.exit(1);
	});
}