tokenlite-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Beiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# LiteMCP
+
+A drop-in replacement for the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) that adds **intelligent tool discovery** for MCP clients.
+
+## The Problem
+
+Many AI agents and MCP clients don't have native tool searching. When your server exposes 50+ tools, the client loads *all* tool definitions into the LLM context - wasting tokens and overwhelming the model.
+
+LiteMCP solves this by wrapping your tools with:
+
+- **`search`** - BM25-ranked tool discovery by name/description
+- **`execute`** - Run any tool by name with arguments
+
+Now clients can search for relevant tools instead of loading everything upfront.
+
+## Token Savings
+
+With 10 tools, LiteMCP reduces base context usage by **~80%**:
+
+```
+┌─────────────────┬─────────────┐
+│ Approach        │ Tokens      │
+├─────────────────┼─────────────┤
+│ Traditional MCP │         917 │
+│ LiteMCP (base)  │         162 │
+└─────────────────┴─────────────┘
+```
+
+Run `bun run compare-tokens` to see stats for your own tools.
+
+## Installation
+
+```bash
+bun add lean-mcp
+# or
+npm install lean-mcp
+```
+
+## Usage
+
+LiteMCP has the **exact same API** as `McpServer`:
+
+```typescript
+import { LiteMCP } from 'lean-mcp';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new LiteMCP({ name: 'my-server', version: '1.0.0' });
+
+// Register tools exactly like McpServer
+server.registerTool(
+  'create_user',
+  {
+    description: 'Create a new user account',
+    inputSchema: {
+      email: z.string().email(),
+      name: z.string(),
+    },
+  },
+  async ({ email, name }) => ({
+    content: [{ type: 'text', text: JSON.stringify({ id: '123', email, name }) }],
+  })
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## What Clients See
+
+Instead of all your tools, clients see two meta-tools:
+
+```json
+{
+  "tools": [
+    { "name": "search", "description": "Search available tools..." },
+    { "name": "execute", "description": "Execute a tool by name..." }
+  ]
+}
+```
+
+### Search with BM25 Ranking
+
+```json
+// Request
+{ "name": "search", "arguments": { "query": "user" } }
+
+// Response - ranked by relevance
+{
+  "tools": [
+    { "name": "create_user", "description": "Create a new user account", "inputSchema": {...} },
+    { "name": "get_user", "description": "Get user by ID", "inputSchema": {...} },
+    { "name": "delete_user", "description": "Delete a user", "inputSchema": {...} }
+  ],
+  "total": 3,
+  "limit": 10
+}
+```
+
+Search features:
+- Splits `snake_case` and `camelCase` into words
+- Matches across name and description
+- IDF-weighted scoring (rare terms rank higher)
+- Exact name matches get boosted
+
+### Execute Tools
+
+```json
+// Request
+{ "name": "execute", "arguments": { "tool": "create_user", "arguments": { "email": "a@b.com", "name": "Alice" } } }
+
+// Response
+{ "content": [{ "type": "text", "text": "{\"id\":\"123\",\"email\":\"a@b.com\",\"name\":\"Alice\"}" }] }
+```
+
+## Options
+
+```typescript
+const server = new LiteMCP(
+  { name: 'my-server', version: '1.0.0' },
+  {
+    liteMode: true,  // Enable search+execute (default: true)
+                     // Set to false for traditional MCP behavior
+  }
+);
+```
+
+## Programmatic Token Stats
+
+```typescript
+const stats = server.getTokenStats();
+console.log(stats);
+// {
+//   toolCount: 10,
+//   traditional: { tokens: 917, characters: 3667 },
+//   liteMcp: { baseTokens: 162, baseCharacters: 646, avgSearchTokens: 283 },
+//   savingsPercent: 82
+// }
+```
+
+## Development
+
+```bash
+bun install          # Install dependencies
+bun test             # Run tests (40 tests)
+bun run example      # Run example server
+bun run inspector    # Test with MCP Inspector
+bun run compare-tokens  # See token comparison
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LiteMCP } from './litemcp.js';
+export type { CallToolResult, Tool, Implementation, RegisteredTool, ServerOptions, Transport, TokenStats, LiteMCPOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,YAAY,EACV,cAAc,EACd,IAAI,EACJ,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { LiteMCP } from './litemcp.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/litemcp.d.ts

@@ -0,0 +1,19 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Implementation } from '@modelcontextprotocol/sdk/types.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { TokenStats, LiteMCPOptions } from './types.js';
+export declare class LiteMCP extends McpServer {
+    private readonly _liteMode;
+    constructor(serverInfo: Implementation, options?: LiteMCPOptions);
+    /** Check if lite mode is enabled */
+    get liteMode(): boolean;
+    connect(transport: Transport): Promise<void>;
+    private handleSearch;
+    /**
+     * Get token usage statistics comparing traditional MCP vs LiteMCP approach.
+     * Uses ~4 characters per token as approximation.
+     */
+    getTokenStats(): TokenStats;
+    private handleExecute;
+}
+//# sourceMappingURL=litemcp.d.ts.map

package/dist/litemcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"litemcp.d.ts","sourceRoot":"","sources":["../src/litemcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAuB,MAAM,yCAAyC,CAAC;AAEzF,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,qBAAa,OAAQ,SAAQ,SAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;gBAExB,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,cAAc;IAKhE,oCAAoC;IACpC,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAEc,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAoF3D,OAAO,CAAC,YAAY;IAsCpB;;;OAGG;IACH,aAAa,IAAI,UAAU;YA4Eb,aAAa;CA+C5B"}

package/dist/litemcp.js

@@ -0,0 +1,222 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+import { bm25Search } from './search.js';
+export class LiteMCP extends McpServer {
+    _liteMode;
+    constructor(serverInfo, options) {
+        super(serverInfo, options);
+        this._liteMode = options?.liteMode ?? true;
+    }
+    /** Check if lite mode is enabled */
+    get liteMode() {
+        return this._liteMode;
+    }
+    async connect(transport) {
+        // Access private _registeredTools via any cast
+        const registeredTools = this
+            ._registeredTools;
+        // If not in lite mode, use default SDK behavior
+        if (!this._liteMode) {
+            await super.connect(transport);
+            return;
+        }
+        // Build lite mode tool definitions
+        const searchTool = {
+            name: 'search',
+            description: 'Search available tools. Returns tool names, descriptions, and input schemas.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Filter by name or description',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Max results to return (default: 10)',
+                    },
+                },
+            },
+        };
+        const executeTool = {
+            name: 'execute',
+            description: 'Execute a tool by name with the provided arguments.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tool: {
+                        type: 'string',
+                        description: 'Name of the tool to execute',
+                    },
+                    arguments: {
+                        type: 'object',
+                        description: 'Arguments to pass to the tool',
+                        additionalProperties: true,
+                    },
+                },
+                required: ['tool'],
+            },
+        };
+        // Override tools/list to expose only search + execute
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return { tools: [searchTool, executeTool] };
+        });
+        // Override tools/call to route through search/execute
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args = {} } = request.params;
+            if (name === 'search') {
+                return this.handleSearch(registeredTools, args['query'], args['limit']);
+            }
+            if (name === 'execute') {
+                return this.handleExecute(registeredTools, args['tool'], (args['arguments'] ?? {}));
+            }
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Unknown tool: ${name}. Use 'search' and 'execute'.` }],
+            };
+        });
+        await super.connect(transport);
+    }
+    handleSearch(registeredTools, query, limit = 10) {
+        const tools = Object.entries(registeredTools)
+            .filter(([, tool]) => tool.enabled)
+            .map(([name, tool]) => ({
+            name,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+                ? toJsonSchemaCompat(tool.inputSchema)
+                : undefined,
+        }));
+        // Use BM25 ranking when query is provided
+        let results;
+        if (query) {
+            const ranked = bm25Search(tools, query);
+            results = ranked.map((r) => r.doc);
+        }
+        else {
+            results = tools;
+        }
+        // Apply limit
+        const total = results.length;
+        const limited = results.slice(0, limit);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ tools: limited, total, limit }, null, 2),
+                },
+            ],
+        };
+    }
+    /**
+     * Get token usage statistics comparing traditional MCP vs LiteMCP approach.
+     * Uses ~4 characters per token as approximation.
+     */
+    getTokenStats() {
+        const registeredTools = this
+            ._registeredTools;
+        // Build all tool schemas as they'd appear in traditional tools/list
+        const allToolSchemas = Object.entries(registeredTools)
+            .filter(([, tool]) => tool.enabled)
+            .map(([name, tool]) => ({
+            name,
+            description: tool.description,
+            inputSchema: tool.inputSchema ? toJsonSchemaCompat(tool.inputSchema) : undefined,
+        }));
+        const traditionalJson = JSON.stringify({ tools: allToolSchemas });
+        // LiteMCP base: just search + execute
+        const liteMcpBase = JSON.stringify({
+            tools: [
+                {
+                    name: 'search',
+                    description: 'Search available tools. Returns tool names, descriptions, and input schemas.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: { type: 'string', description: 'Filter by name or description' },
+                            limit: { type: 'number', description: 'Max results to return (default: 10)' },
+                        },
+                    },
+                },
+                {
+                    name: 'execute',
+                    description: 'Execute a tool by name with the provided arguments.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            tool: { type: 'string', description: 'Name of the tool to execute' },
+                            arguments: { type: 'object', description: 'Arguments to pass to the tool', additionalProperties: true },
+                        },
+                        required: ['tool'],
+                    },
+                },
+            ],
+        });
+        // Estimate tokens (~4 chars per token)
+        const charsPerToken = 4;
+        const traditionalTokens = Math.ceil(traditionalJson.length / charsPerToken);
+        const liteMcpBaseTokens = Math.ceil(liteMcpBase.length / charsPerToken);
+        // Average search result (3 tools)
+        const sampleSearchResult = JSON.stringify({
+            tools: allToolSchemas.slice(0, 3),
+            total: allToolSchemas.length,
+            limit: 10,
+        });
+        const avgSearchTokens = Math.ceil(sampleSearchResult.length / charsPerToken);
+        const savings = traditionalTokens > 0
+            ? Math.round((1 - liteMcpBaseTokens / traditionalTokens) * 100)
+            : 0;
+        return {
+            toolCount: allToolSchemas.length,
+            traditional: {
+                tokens: traditionalTokens,
+                characters: traditionalJson.length,
+            },
+            liteMcp: {
+                baseTokens: liteMcpBaseTokens,
+                baseCharacters: liteMcpBase.length,
+                avgSearchTokens,
+            },
+            savingsPercent: savings,
+        };
+    }
+    async handleExecute(registeredTools, toolName, args) {
+        const tool = registeredTools[toolName];
+        if (!tool) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Unknown tool: "${toolName}". Use the search tool to list available tools.`,
+                    },
+                ],
+            };
+        }
+        if (!tool.enabled) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Tool "${toolName}" is disabled.` }],
+            };
+        }
+        try {
+            // Call the original handler
+            const handler = tool.handler;
+            const result = await handler(args, {});
+            return result;
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Tool error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    }
+}
+//# sourceMappingURL=litemcp.js.map

package/dist/litemcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"litemcp.js","sourceRoot":"","sources":["../src/litemcp.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -0,0 +1,27 @@
+/**
+ * BM25 search implementation for tool discovery.
+ *
+ * BM25 (Best Matching 25) is a ranking function used by search engines.
+ * It considers term frequency, document length, and inverse document frequency.
+ */
+/** A searchable document with name and optional description */
+export interface SearchableDoc {
+    name: string;
+    description?: string;
+}
+/** Search result with relevance score */
+export interface SearchResult<T extends SearchableDoc> {
+    doc: T;
+    score: number;
+}
+/**
+ * BM25 search implementation.
+ *
+ * @param docs - Documents to search
+ * @param query - Search query string
+ * @param k1 - Term frequency saturation (default: 1.5)
+ * @param b - Document length normalization (default: 0.75)
+ * @returns Sorted results with scores (highest first)
+ */
+export declare function bm25Search<T extends SearchableDoc>(docs: T[], query: string, k1?: number, b?: number): SearchResult<T>[];
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,aAAa;IACnD,GAAG,EAAE,CAAC,CAAC;IACP,KAAK,EAAE,MAAM,CAAC;CACf;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,aAAa,EAChD,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,EAAE,SAAM,EACR,CAAC,SAAO,GACP,YAAY,CAAC,CAAC,CAAC,EAAE,CAqEnB"}

package/dist/search.js

@@ -0,0 +1,90 @@
+/**
+ * BM25 search implementation for tool discovery.
+ *
+ * BM25 (Best Matching 25) is a ranking function used by search engines.
+ * It considers term frequency, document length, and inverse document frequency.
+ */
+/**
+ * Tokenize text into searchable terms.
+ * Splits on word boundaries, lowercases, and handles snake_case/camelCase.
+ */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        // Split camelCase: "createUser" -> "create User"
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        // Split snake_case: "create_user" -> "create user"
+        .replace(/_/g, ' ')
+        // Split on non-alphanumeric
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * BM25 search implementation.
+ *
+ * @param docs - Documents to search
+ * @param query - Search query string
+ * @param k1 - Term frequency saturation (default: 1.5)
+ * @param b - Document length normalization (default: 0.75)
+ * @returns Sorted results with scores (highest first)
+ */
+export function bm25Search(docs, query, k1 = 1.5, b = 0.75) {
+    if (!query.trim()) {
+        // No query = return all with score 0
+        return docs.map((doc) => ({ doc, score: 0 }));
+    }
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0) {
+        return docs.map((doc) => ({ doc, score: 0 }));
+    }
+    // Build corpus: combine name + description for each doc
+    const corpus = docs.map((doc) => {
+        const text = `${doc.name} ${doc.description ?? ''}`;
+        return tokenize(text);
+    });
+    // Calculate average document length
+    const totalLength = corpus.reduce((sum, terms) => sum + terms.length, 0);
+    const avgdl = totalLength / corpus.length || 1;
+    // Calculate IDF for each query term
+    const N = docs.length;
+    const idf = new Map();
+    for (const term of queryTerms) {
+        // Count documents containing this term
+        const docsWithTerm = corpus.filter((docTerms) => docTerms.includes(term)).length;
+        // IDF formula: log((N - n + 0.5) / (n + 0.5) + 1)
+        const idfValue = Math.log((N - docsWithTerm + 0.5) / (docsWithTerm + 0.5) + 1);
+        idf.set(term, idfValue);
+    }
+    // Calculate BM25 score for each document
+    const results = docs.map((doc, i) => {
+        const docTerms = corpus[i] ?? [];
+        const docLength = docTerms.length;
+        let score = 0;
+        for (const term of queryTerms) {
+            // Term frequency in this document
+            const tf = docTerms.filter((t) => t === term).length;
+            if (tf === 0)
+                continue;
+            const termIdf = idf.get(term) ?? 0;
+            // BM25 formula
+            const numerator = tf * (k1 + 1);
+            const denominator = tf + k1 * (1 - b + b * (docLength / avgdl));
+            score += termIdf * (numerator / denominator);
+        }
+        // Boost exact name matches
+        const nameLower = doc.name.toLowerCase();
+        const queryLower = query.toLowerCase();
+        if (nameLower === queryLower) {
+            score += 10; // Strong boost for exact match
+        }
+        else if (nameLower.includes(queryLower)) {
+            score += 2; // Mild boost for substring match in name
+        }
+        return { doc, score };
+    });
+    // Filter to only docs with positive scores and sort by score descending
+    return results
+        .filter((r) => r.score > 0)
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH;;;GAGG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI;SACR,WAAW,EAAE;QACd,iDAAiD;SAChD,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC;QACpC,mDAAmD;SAClD,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;QACnB,4BAA4B;SAC3B,KAAK,CAAC,YAAY,CAAC;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CACxB,IAAS,EACT,KAAa,EACb,EAAE,GAAG,GAAG,EACR,CAAC,GAAG,IAAI;IAER,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,qCAAqC;QACrC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,wDAAwD;IACxD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;QACpD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,oCAAoC;IACpC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,WAAW,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAE/C,oCAAoC;IACpC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,uCAAuC;QACvC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QACjF,kDAAkD;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/E,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,yCAAyC;IACzC,MAAM,OAAO,GAAsB,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;QAElC,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,kCAAkC;YAClC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;YACrD,IAAI,EAAE,KAAK,CAAC;gBAAE,SAAS;YAEvB,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEnC,eAAe;YACf,MAAM,SAAS,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAChC,MAAM,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC;YAChE,KAAK,IAAI,OAAO,GAAG,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;QAC/C,CAAC;QAED,2BAA2B;QAC3B,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;YAC7B,KAAK,IAAI,EAAE,CAAC,CAAC,+BAA+B;QAC9C,CAAC;aAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1C,KAAK,IAAI,CAAC,CAAC,CAAC,yCAAyC;QACvD,CAAC;QAED,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,wEAAwE;IACxE,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;SAC1B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+export type { CallToolResult, Tool, Implementation, } from '@modelcontextprotocol/sdk/types.js';
+export type { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
+export type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
+/** LiteMCP server options */
+export interface LiteMCPOptions extends ServerOptions {
+    /**
+     * Enable lite mode (search + execute).
+     * When false, behaves like standard McpServer (all tools exposed directly).
+     * @default true
+     */
+    liteMode?: boolean;
+}
+/** Token usage statistics for comparing traditional MCP vs LiteMCP */
+export interface TokenStats {
+    /** Number of registered tools */
+    toolCount: number;
+    /** Traditional MCP approach (all tools in tools/list) */
+    traditional: {
+        tokens: number;
+        characters: number;
+    };
+    /** LiteMCP approach (search + execute only) */
+    liteMcp: {
+        /** Base tokens for search + execute tools */
+        baseTokens: number;
+        baseCharacters: number;
+        /** Average tokens for a search result (3 tools) */
+        avgSearchTokens: number;
+    };
+    /** Percentage savings in base context */
+    savingsPercent: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,YAAY,EACV,cAAc,EACd,IAAI,EACJ,cAAc,GACf,MAAM,oCAAoC,CAAC;AAE5C,YAAY,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAE9E,YAAY,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,YAAY,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAC;AAE/E,6BAA6B;AAC7B,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,+CAA+C;IAC/C,OAAO,EAAE;QACP,6CAA6C;QAC7C,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,mDAAmD;QACnD,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "tokenlite-mcp",
+  "version": "0.1.0",
+  "description": "Lightweight MCP proxy wrapper for tool interception and composition",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "build": "tsc",
+    "start": "bun run src/index.ts",
+    "test": "bun test",
+    "lint": "eslint src/",
+    "format": "prettier --write src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build && bun test",
+    "example": "bun run examples/basic.ts",
+    "inspector": "npx @modelcontextprotocol/inspector bun run examples/basic.ts",
+    "compare-tokens": "bun run scripts/compare-tokens.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "proxy",
+    "tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3"
+  }
+}