feat: add TOON output format for token-efficient LLM responses (#155)

Implement TOON (Token-Oriented Object Notation) as the default output format
for all Jira API responses, providing 30-60% token reduction compared to JSON.

Changes:
- Add @toon-format/toon package dependency
- Create toon.util.ts with TOON conversion logic and JSON fallback
- Add toOutputString function to jq.util.ts for format conversion
- Add outputFormat parameter to all tool types (toon/json)
- Update controller to respect outputFormat parameter (defaults to TOON)
- Add --output-format CLI option to all commands
- Update all tool descriptions with:
  * TOON as default output format
  * Cost optimization warnings (always use jq filter)
  * Schema discovery pattern (fetch one item first to explore fields)
- Add comprehensive test coverage for TOON utilities

TOON conversion falls back to JSON if encoding fails, ensuring reliability.

Author: aashari

package-lock.json

@@ -96,6 +96,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.5",
+    "@toon-format/toon": "^2.0.1",
     "commander": "^14.0.0",
     "cors": "^2.8.5",
     "dotenv": "^17.2.2",

package.json

@@ -68,6 +68,7 @@ function registerReadCommand(
 		path: string;
 		queryParams?: Record<string, string>;
 		jq?: string;
+		outputFormat?: 'toon' | 'json';
 	}) => Promise<{ content: string }>,
 ): void {
 	program
@@ -85,6 +86,11 @@ function registerReadCommand(
 			'--jq <expression>',
 			'JMESPath expression to filter/transform the response.',
 		)
+		.option(
+			'--output-format <format>',
+			'Output format: "toon" (default, token-efficient) or "json".',
+			'toon',
+		)
 		.action(async (options) => {
 			const actionLogger = cliLogger.forMethod(name);
 			try {
@@ -103,6 +109,7 @@ function registerReadCommand(
 					path: options.path,
 					queryParams,
 					jq: options.jq,
+					outputFormat: options.outputFormat as 'toon' | 'json',
 				});
 
 				console.log(result.content);
@@ -128,6 +135,7 @@ function registerWriteCommand(
 		body: Record<string, unknown>;
 		queryParams?: Record<string, string>;
 		jq?: string;
+		outputFormat?: 'toon' | 'json';
 	}) => Promise<{ content: string }>,
 ): void {
 	program
@@ -143,6 +151,11 @@ function registerWriteCommand(
 			'--jq <expression>',
 			'JMESPath expression to filter/transform the response.',
 		)
+		.option(
+			'--output-format <format>',
+			'Output format: "toon" (default, token-efficient) or "json".',
+			'toon',
+		)
 		.action(async (options) => {
 			const actionLogger = cliLogger.forMethod(name);
 			try {
@@ -168,6 +181,7 @@ function registerWriteCommand(
 					body,
 					queryParams,
 					jq: options.jq,
+					outputFormat: options.outputFormat as 'toon' | 'json',
 				});
 
 				console.log(result.content);
@@ -193,39 +207,39 @@ function register(program: Command): void {
 	registerReadCommand(
 		program,
 		'get',
-		'GET any Jira endpoint. Returns JSON, optionally filtered with JMESPath.',
+		'GET any Jira endpoint. Returns TOON by default (or JSON with --output-format json), optionally filtered with JMESPath.',
 		handleGet,
 	);
 
 	// Register POST command
 	registerWriteCommand(
 		program,
 		'post',
-		'POST to any Jira endpoint. Returns JSON, optionally filtered with JMESPath.',
+		'POST to any Jira endpoint. Returns TOON by default (or JSON with --output-format json), optionally filtered with JMESPath.',
 		handlePost,
 	);
 
 	// Register PUT command
 	registerWriteCommand(
 		program,
 		'put',
-		'PUT to any Jira endpoint. Returns JSON, optionally filtered with JMESPath.',
+		'PUT to any Jira endpoint. Returns TOON by default (or JSON with --output-format json), optionally filtered with JMESPath.',
 		handlePut,
 	);
 
 	// Register PATCH command
 	registerWriteCommand(
 		program,
 		'patch',
-		'PATCH any Jira endpoint. Returns JSON, optionally filtered with JMESPath.',
+		'PATCH any Jira endpoint. Returns TOON by default (or JSON with --output-format json), optionally filtered with JMESPath.',
 		handlePatch,
 	);
 
 	// Register DELETE command
 	registerReadCommand(
 		program,
 		'delete',
-		'DELETE any Jira endpoint. Returns JSON (if any), optionally filtered with JMESPath.',
+		'DELETE any Jira endpoint. Returns TOON by default (or JSON with --output-format json, if any), optionally filtered with JMESPath.',
 		handleDelete,
 	);
 

src/cli/atlassian.api.cli.ts

@@ -9,7 +9,7 @@ import {
 	GetApiToolArgsType,
 	RequestWithBodyArgsType,
 } from '../tools/atlassian.api.types.js';
-import { applyJqFilter, toJsonString } from '../utils/jq.util.js';
+import { applyJqFilter, toOutputString } from '../utils/jq.util.js';
 import { createAuthMissingError } from '../utils/error.util.js';
 
 // Logger instance for this module
@@ -20,13 +20,19 @@ const logger = Logger.forContext('controllers/atlassian.api.controller.ts');
  */
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 
+/**
+ * Output format type
+ */
+type OutputFormat = 'toon' | 'json';
+
 /**
  * Base options for all API requests
  */
 interface BaseRequestOptions {
 	path: string;
 	queryParams?: Record<string, string>;
 	jq?: string;
+	outputFormat?: OutputFormat;
 }
 
 /**
@@ -119,8 +125,12 @@ async function handleRequest(
 		// Apply JQ filter if provided, otherwise return raw data
 		const result = applyJqFilter(response, options.jq);
 
+		// Convert to output format (TOON by default, JSON if requested)
+		const useToon = options.outputFormat !== 'json';
+		const content = await toOutputString(result, useToon);
+
 		return {
-			content: toJsonString(result),
+			content,
 		};
 	} catch (error) {
 		throw handleControllerError(error, {

src/controllers/atlassian.api.controller.ts

@@ -125,7 +125,18 @@ function registerTools(server: McpServer) {
 	// Register the GET tool
 	server.tool(
 		'jira_get',
-		`Read any Jira data. Returns JSON, optionally filtered with JMESPath (\`jq\` param).
+		`Read any Jira data. Returns TOON format by default (30-60% fewer tokens than JSON).
+
+**IMPORTANT - Cost Optimization:**
+- ALWAYS use \`jq\` param to filter response fields. Unfiltered responses are very expensive!
+- Use \`maxResults\` query param to restrict result count (e.g., \`maxResults: "5"\`)
+- If unsure about available fields, first fetch ONE item with \`maxResults: "1"\` and NO jq filter to explore the schema, then use jq in subsequent calls
+
+**Schema Discovery Pattern:**
+1. First call: \`path: "/rest/api/3/search", queryParams: {"maxResults": "1", "jql": "project=PROJ"}\` (no jq) - explore available fields
+2. Then use: \`jq: "issues[*].{key: key, summary: fields.summary, status: fields.status.name}"\` - extract only what you need
+
+**Output format:** TOON (default, token-efficient) or JSON (\`outputFormat: "json"\`)
 
 **Common paths:**
 - \`/rest/api/3/project\` - list all projects
@@ -140,7 +151,7 @@ function registerTools(server: McpServer) {
 - \`/rest/api/3/issuetype\` - list issue types
 - \`/rest/api/3/priority\` - list priorities
 
-**Query params:** \`maxResults\` (page size), \`startAt\` (offset), \`jql\` (JQL query), \`fields\` (field selection), \`expand\` (include additional data)
+**JQ examples:** \`issues[*].key\`, \`issues[0]\`, \`issues[*].{key: key, summary: fields.summary}\`
 
 **Example JQL queries:** \`project=PROJ\`, \`assignee=currentUser()\`, \`status="In Progress"\`, \`created >= -7d\`
 
@@ -152,7 +163,13 @@ API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/`,
 	// Register the POST tool
 	server.tool(
 		'jira_post',
-		`Create Jira resources. Returns JSON, optionally filtered with JMESPath (\`jq\` param).
+		`Create Jira resources. Returns TOON format by default (token-efficient).
+
+**IMPORTANT - Cost Optimization:**
+- Use \`jq\` param to extract only needed fields from response (e.g., \`jq: "{key: key, id: id}"\`)
+- Unfiltered responses include all metadata and are expensive!
+
+**Output format:** TOON (default) or JSON (\`outputFormat: "json"\`)
 
 **Common operations:**
 
@@ -179,7 +196,11 @@ API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/`,
 	// Register the PUT tool
 	server.tool(
 		'jira_put',
-		`Replace Jira resources (full update). Returns JSON, optionally filtered with JMESPath (\`jq\` param).
+		`Replace Jira resources (full update). Returns TOON format by default.
+
+**IMPORTANT - Cost Optimization:** Use \`jq\` param to extract only needed fields from response
+
+**Output format:** TOON (default) or JSON (\`outputFormat: "json"\`)
 
 **Common operations:**
 
@@ -202,7 +223,11 @@ API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/`,
 	// Register the PATCH tool
 	server.tool(
 		'jira_patch',
-		`Partially update Jira resources. Returns JSON, optionally filtered with JMESPath (\`jq\` param).
+		`Partially update Jira resources. Returns TOON format by default.
+
+**IMPORTANT - Cost Optimization:** Use \`jq\` param to filter response fields.
+
+**Output format:** TOON (default) or JSON (\`outputFormat: "json"\`)
 
 **Common operations:**
 
@@ -225,7 +250,9 @@ API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/`,
 	// Register the DELETE tool
 	server.tool(
 		'jira_delete',
-		`Delete Jira resources. Returns JSON (if any), optionally filtered with JMESPath (\`jq\` param).
+		`Delete Jira resources. Returns TOON format by default.
+
+**Output format:** TOON (default) or JSON (\`outputFormat: "json"\`)
 
 **Common operations:**
 

src/tools/atlassian.api.tool.ts

@@ -1,8 +1,20 @@
 import { z } from 'zod';
 
+/**
+ * Output format options for API responses
+ * - toon: Token-Oriented Object Notation (default, more token-efficient for LLMs)
+ * - json: Standard JSON format
+ */
+export const OutputFormat = z
+	.enum(['toon', 'json'])
+	.optional()
+	.describe(
+		'Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.',
+	);
+
 /**
  * Base schema fields shared by all API tool arguments
- * Contains path, queryParams, and jq filter
+ * Contains path, queryParams, jq filter, and outputFormat
  */
 const BaseApiToolArgs = {
 	/**
@@ -33,13 +45,20 @@ const BaseApiToolArgs = {
 
 	/**
 	 * Optional JMESPath expression to filter/transform the response
+	 * IMPORTANT: Always use this to reduce response size and token costs
 	 */
 	jq: z
 		.string()
 		.optional()
 		.describe(
-			'JMESPath expression to filter/transform the JSON response. Examples: "issues[*].key" (extract keys), "total" (single field), "{key: key, summary: fields.summary}" (reshape object). See https://jmespath.org for syntax.',
+			'JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "issues[*].{key: key, summary: fields.summary}" (extract specific fields), "issues[0]" (first result), "issues[*].key" (keys only). See https://jmespath.org',
 		),
+
+	/**
+	 * Output format for the response
+	 * Defaults to TOON (token-efficient), can be set to JSON if needed
+	 */
+	outputFormat: OutputFormat,
 };
 
 /**

src/tools/atlassian.api.types.ts

@@ -1,5 +1,6 @@
 import jmespath from 'jmespath';
 import { Logger } from './logger.util.js';
+import { toToonOrJson } from './toon.util.js';
 
 const logger = Logger.forContext('utils/jq.util.ts');
 
@@ -60,3 +61,31 @@ export function toJsonString(data: unknown, pretty: boolean = true): string {
 	}
 	return JSON.stringify(data);
 }
+
+/**
+ * Convert data to output string for MCP response
+ *
+ * By default, converts to TOON format (Token-Oriented Object Notation)
+ * for improved LLM token efficiency (30-60% fewer tokens).
+ * Falls back to JSON if TOON conversion fails or if useToon is false.
+ *
+ * @param data - The data to convert
+ * @param useToon - Whether to use TOON format (default: true)
+ * @param pretty - Whether to pretty-print JSON (default: true)
+ * @returns TOON formatted string (default), or JSON string
+ */
+export async function toOutputString(
+	data: unknown,
+	useToon: boolean = true,
+	pretty: boolean = true,
+): Promise<string> {
+	const jsonString = toJsonString(data, pretty);
+
+	// Return JSON directly if TOON is not requested
+	if (!useToon) {
+		return jsonString;
+	}
+
+	// Try TOON conversion with JSON fallback
+	return toToonOrJson(data, jsonString);
+}