@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/token-tracking.ts

@@ -1,167 +1,167 @@
-/**
- * Token Tracking Utilities
- *
- * Functions for estimating and tracking token usage across MCP tool calls.
- * Extracted from index.ts to enable unit testing.
- */
-
-import { getErrorMessage } from './utils.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface ModelTokens {
-	input: number;
-	output: number;
-}
-
-export interface TokenUsage {
-	callCount: number;
-	totalTokens: number;
-	byTool: Record<string, { calls: number; tokens: number }>;
-	byModel: Record<string, ModelTokens>;
-	currentModel: string | null;
-}
-
-// ============================================================================
-// Token Estimation
-// ============================================================================
-
-/**
- * Estimate tokens from a JSON-serializable object.
- * Uses a rough heuristic of ~4 characters per token.
- *
- * @param obj - Any JSON-serializable object
- * @returns Estimated token count (always >= 1)
- */
-export function estimateTokens(obj: unknown): number {
-	try {
-		const json = JSON.stringify(obj);
-		return Math.max(1, Math.ceil(json.length / 4));
-	} catch (error) {
-		// Log warning when serialization fails (e.g., circular references, BigInt)
-		console.warn(`[Vibescope] Token estimation failed: ${getErrorMessage(error)}. Returning minimal estimate of 1 token.`);
-		return 1;
-	}
-}
-
-// ============================================================================
-// Token Usage Tracking
-// ============================================================================
-
-/**
- * Create a fresh token usage tracker.
- */
-export function createTokenUsage(): TokenUsage {
-	return {
-		callCount: 0,
-		totalTokens: 0,
-		byTool: {},
-		byModel: {},
-		currentModel: null,
-	};
-}
-
-/**
- * Track token usage for a tool call.
- * Updates the usage object in-place with input/output token estimates.
- *
- * @param usage - The token usage object to update
- * @param toolName - Name of the tool being called
- * @param args - Input arguments to the tool
- * @param response - Response from the tool
- */
-export function trackTokenUsage(
-	usage: TokenUsage,
-	toolName: string,
-	args: unknown,
-	response: unknown
-): void {
-	const inputTokens = estimateTokens(args);
-	const outputTokens = estimateTokens(response);
-	const totalTokens = inputTokens + outputTokens;
-
-	usage.callCount++;
-	usage.totalTokens += totalTokens;
-
-	if (!usage.byTool[toolName]) {
-		usage.byTool[toolName] = { calls: 0, tokens: 0 };
-	}
-	usage.byTool[toolName].calls++;
-	usage.byTool[toolName].tokens += totalTokens;
-
-	// Track by model if a model is set
-	const model = usage.currentModel;
-	if (model) {
-		if (!usage.byModel[model]) {
-			usage.byModel[model] = { input: 0, output: 0 };
-		}
-		usage.byModel[model].input += inputTokens;
-		usage.byModel[model].output += outputTokens;
-	}
-}
-
-/**
- * Set the current model for token tracking.
- * Subsequent calls to trackTokenUsage will be attributed to this model.
- *
- * @param usage - The token usage object to update
- * @param model - Model name (e.g., "opus", "sonnet", "haiku")
- */
-export function setCurrentModel(usage: TokenUsage, model: string | null): void {
-	usage.currentModel = model;
-}
-
-/**
- * Reset token usage tracking to initial state.
- *
- * @param usage - The token usage object to reset
- */
-export function resetTokenUsage(usage: TokenUsage): void {
-	usage.callCount = 0;
-	usage.totalTokens = 0;
-	usage.byTool = {};
-	usage.byModel = {};
-	usage.currentModel = null;
-}
-
-/**
- * Get a summary of token usage for reporting.
- *
- * @param usage - The token usage object
- * @returns Summary object with stats
- */
-export function getTokenUsageSummary(usage: TokenUsage): {
-	total_calls: number;
-	total_tokens: number;
-	average_tokens_per_call: number;
-	by_tool: Record<string, { calls: number; tokens: number; avg: number }>;
-	by_model: Record<string, ModelTokens>;
-	current_model: string | null;
-} {
-	const byTool: Record<string, { calls: number; tokens: number; avg: number }> = {};
-
-	for (const [tool, stats] of Object.entries(usage.byTool)) {
-		byTool[tool] = {
-			calls: stats.calls,
-			tokens: stats.tokens,
-			avg: stats.calls > 0 ? Math.round(stats.tokens / stats.calls) : 0,
-		};
-	}
-
-	// Deep copy byModel to prevent mutation
-	const byModel: Record<string, ModelTokens> = {};
-	for (const [model, tokens] of Object.entries(usage.byModel)) {
-		byModel[model] = { input: tokens.input, output: tokens.output };
-	}
-
-	return {
-		total_calls: usage.callCount,
-		total_tokens: usage.totalTokens,
-		average_tokens_per_call: usage.callCount > 0 ? Math.round(usage.totalTokens / usage.callCount) : 0,
-		by_tool: byTool,
-		by_model: byModel,
-		current_model: usage.currentModel,
-	};
-}
+/**
+ * Token Tracking Utilities
+ *
+ * Functions for estimating and tracking token usage across MCP tool calls.
+ * Extracted from index.ts to enable unit testing.
+ */
+
+import { getErrorMessage } from './utils.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ModelTokens {
+	input: number;
+	output: number;
+}
+
+export interface TokenUsage {
+	callCount: number;
+	totalTokens: number;
+	byTool: Record<string, { calls: number; tokens: number }>;
+	byModel: Record<string, ModelTokens>;
+	currentModel: string | null;
+}
+
+// ============================================================================
+// Token Estimation
+// ============================================================================
+
+/**
+ * Estimate tokens from a JSON-serializable object.
+ * Uses a rough heuristic of ~4 characters per token.
+ *
+ * @param obj - Any JSON-serializable object
+ * @returns Estimated token count (always >= 1)
+ */
+export function estimateTokens(obj: unknown): number {
+	try {
+		const json = JSON.stringify(obj);
+		return Math.max(1, Math.ceil(json.length / 4));
+	} catch (error) {
+		// Log warning when serialization fails (e.g., circular references, BigInt)
+		console.warn(`[Vibescope] Token estimation failed: ${getErrorMessage(error)}. Returning minimal estimate of 1 token.`);
+		return 1;
+	}
+}
+
+// ============================================================================
+// Token Usage Tracking
+// ============================================================================
+
+/**
+ * Create a fresh token usage tracker.
+ */
+export function createTokenUsage(): TokenUsage {
+	return {
+		callCount: 0,
+		totalTokens: 0,
+		byTool: {},
+		byModel: {},
+		currentModel: null,
+	};
+}
+
+/**
+ * Track token usage for a tool call.
+ * Updates the usage object in-place with input/output token estimates.
+ *
+ * @param usage - The token usage object to update
+ * @param toolName - Name of the tool being called
+ * @param args - Input arguments to the tool
+ * @param response - Response from the tool
+ */
+export function trackTokenUsage(
+	usage: TokenUsage,
+	toolName: string,
+	args: unknown,
+	response: unknown
+): void {
+	const inputTokens = estimateTokens(args);
+	const outputTokens = estimateTokens(response);
+	const totalTokens = inputTokens + outputTokens;
+
+	usage.callCount++;
+	usage.totalTokens += totalTokens;
+
+	if (!usage.byTool[toolName]) {
+		usage.byTool[toolName] = { calls: 0, tokens: 0 };
+	}
+	usage.byTool[toolName].calls++;
+	usage.byTool[toolName].tokens += totalTokens;
+
+	// Track by model if a model is set
+	const model = usage.currentModel;
+	if (model) {
+		if (!usage.byModel[model]) {
+			usage.byModel[model] = { input: 0, output: 0 };
+		}
+		usage.byModel[model].input += inputTokens;
+		usage.byModel[model].output += outputTokens;
+	}
+}
+
+/**
+ * Set the current model for token tracking.
+ * Subsequent calls to trackTokenUsage will be attributed to this model.
+ *
+ * @param usage - The token usage object to update
+ * @param model - Model name (e.g., "opus", "sonnet", "haiku")
+ */
+export function setCurrentModel(usage: TokenUsage, model: string | null): void {
+	usage.currentModel = model;
+}
+
+/**
+ * Reset token usage tracking to initial state.
+ *
+ * @param usage - The token usage object to reset
+ */
+export function resetTokenUsage(usage: TokenUsage): void {
+	usage.callCount = 0;
+	usage.totalTokens = 0;
+	usage.byTool = {};
+	usage.byModel = {};
+	usage.currentModel = null;
+}
+
+/**
+ * Get a summary of token usage for reporting.
+ *
+ * @param usage - The token usage object
+ * @returns Summary object with stats
+ */
+export function getTokenUsageSummary(usage: TokenUsage): {
+	total_calls: number;
+	total_tokens: number;
+	average_tokens_per_call: number;
+	by_tool: Record<string, { calls: number; tokens: number; avg: number }>;
+	by_model: Record<string, ModelTokens>;
+	current_model: string | null;
+} {
+	const byTool: Record<string, { calls: number; tokens: number; avg: number }> = {};
+
+	for (const [tool, stats] of Object.entries(usage.byTool)) {
+		byTool[tool] = {
+			calls: stats.calls,
+			tokens: stats.tokens,
+			avg: stats.calls > 0 ? Math.round(stats.tokens / stats.calls) : 0,
+		};
+	}
+
+	// Deep copy byModel to prevent mutation
+	const byModel: Record<string, ModelTokens> = {};
+	for (const [model, tokens] of Object.entries(usage.byModel)) {
+		byModel[model] = { input: tokens.input, output: tokens.output };
+	}
+
+	return {
+		total_calls: usage.callCount,
+		total_tokens: usage.totalTokens,
+		average_tokens_per_call: usage.callCount > 0 ? Math.round(usage.totalTokens / usage.callCount) : 0,
+		by_tool: byTool,
+		by_model: byModel,
+		current_model: usage.currentModel,
+	};
+}

package/src/tools/blockers.ts

@@ -1,122 +1,122 @@
-/**
- * Blocker Tool Definitions
- *
- * Tools for managing blockers:
- * - add_blocker
- * - resolve_blocker
- * - get_blocker
- * - get_blockers
- * - get_blockers_stats
- * - delete_blocker
- */
-
-import type { Tool } from './types.js';
-
-export const blockerTools: Tool[] = [
-	{
-		name: 'add_blocker',
-		description: `Record a blocker preventing progress.`,
-		inputSchema: {
-			type: 'object',
-			properties: {
-				project_id: {
-					type: 'string',
-					description: 'Project UUID',
-				},
-				description: {
-					type: 'string',
-					description: 'What is blocking progress?',
-				},
-			},
-			required: ['project_id', 'description'],
-		},
-	},
-	{
-		name: 'resolve_blocker',
-		description: `Mark a blocker as resolved.`,
-		inputSchema: {
-			type: 'object',
-			properties: {
-				blocker_id: {
-					type: 'string',
-					description: 'Blocker UUID',
-				},
-				resolution_note: {
-					type: 'string',
-					description: 'How was it resolved?',
-				},
-			},
-			required: ['blocker_id'],
-		},
-	},
-	{
-		name: 'get_blocker',
-		description: `Get a single blocker by ID. More token-efficient than get_blockers when you need details for a specific blocker.`,
-		inputSchema: {
-			type: 'object',
-			properties: {
-				blocker_id: {
-					type: 'string',
-					description: 'Blocker UUID',
-				},
-			},
-			required: ['blocker_id'],
-		},
-	},
-	{
-		name: 'get_blockers',
-		description: `Get blockers for a project, optionally filtered by status.`,
-		inputSchema: {
-			type: 'object',
-			properties: {
-				project_id: {
-					type: 'string',
-					description: 'Project UUID',
-				},
-				status: {
-					type: 'string',
-					enum: ['open', 'resolved'],
-					description: 'Filter by status (default: open)',
-				},
-				limit: {
-					type: 'number',
-					description: 'Max number of blockers to return (default 10, max 200)',
-				},
-				offset: {
-					type: 'number',
-					description: 'Number of blockers to skip for pagination (default 0)',
-				},
-				search_query: {
-					type: 'string',
-					description: 'Search blockers by description',
-				},
-			},
-			required: ['project_id'],
-		},
-	},
-	{
-		name: 'get_blockers_stats',
-		description: `Get aggregate statistics about blockers for a project. Returns total count and breakdown by status. Much more token-efficient than get_blockers when you just need to understand the overall state.`,
-		inputSchema: {
-			type: 'object',
-			properties: {
-				project_id: { type: 'string', description: 'Project UUID' },
-			},
-			required: ['project_id'],
-		},
-	},
-	{
-		name: 'delete_blocker',
-		description: `Delete a blocker.`,
-		inputSchema: {
-			type: 'object',
-			properties: {
-				blocker_id: {
-					type: 'string',
-					description: 'Blocker UUID',
-				},
-			},
-			required: ['blocker_id'],
-		},
-	},
-];
+/**
+ * Blocker Tool Definitions
+ *
+ * Tools for managing blockers:
+ * - add_blocker
+ * - resolve_blocker
+ * - get_blocker
+ * - get_blockers
+ * - get_blockers_stats
+ * - delete_blocker
+ */
+
+import type { Tool } from './types.js';
+
+export const blockerTools: Tool[] = [
+	{
+		name: 'add_blocker',
+		description: `Record a blocker preventing progress.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				description: {
+					type: 'string',
+					description: 'What is blocking progress?',
+				},
+			},
+			required: ['project_id', 'description'],
+		},
+	},
+	{
+		name: 'resolve_blocker',
+		description: `Mark a blocker as resolved.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+				resolution_note: {
+					type: 'string',
+					description: 'How was it resolved?',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+	{
+		name: 'get_blocker',
+		description: `Get a single blocker by ID. More token-efficient than get_blockers when you need details for a specific blocker.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+	{
+		name: 'get_blockers',
+		description: `Get blockers for a project, optionally filtered by status.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['open', 'resolved'],
+					description: 'Filter by status (default: open)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max number of blockers to return (default 10, max 200)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of blockers to skip for pagination (default 0)',
+				},
+				search_query: {
+					type: 'string',
+					description: 'Search blockers by description',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_blockers_stats',
+		description: `Get aggregate statistics about blockers for a project. Returns total count and breakdown by status. Much more token-efficient than get_blockers when you just need to understand the overall state.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: { type: 'string', description: 'Project UUID' },
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_blocker',
+		description: `Delete a blocker.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+];