mcp-cost-tracker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,99 @@
+# MCP Cost Tracker
+
+**An open-source MCP server that automatically tracks LLM API call costs, token usage, and generates visual dashboards.**
+
+[![MCP Server](https://img.shields.io/badge/MCP-Server-blue?style=flat-square)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+`mcp-cost-tracker` is a powerful, easy-to-use MCP server designed for developers who want to monitor and control their LLM API spending. It provides a comprehensive suite of tools to track token usage, calculate costs across 50+ models, set budgets, and visualize spending patterns.
+
+![Dashboard Screenshot](https://raw.githubusercontent.com/your-username/mcp-cost-tracker/main/assets/dashboard.png)  
+*(This is a placeholder image. A real screenshot will be added after the first release.)*
+
+## ✨ Key Features
+
+- **Comprehensive Cost Tracking**: Automatically calculates costs for 50+ models from major providers including OpenAI, Anthropic, Google, DeepSeek, Mistral, and more.
+- **15+ MCP Tools**: A rich set of tools for tracking usage, analyzing costs, setting budgets, comparing models, and exporting data.
+- **Visual Dashboard**: Generate a beautiful, interactive HTML dashboard with charts for daily trends, cost breakdowns by model/provider/project, and top expensive requests.
+- **Budget Management**: Set daily, weekly, or monthly budgets with alerts to prevent cost overruns.
+- **SQLite Persistence**: All usage data is stored locally in a SQLite database, ensuring data ownership and enabling historical analysis.
+- **Easy Integration**: Use as a standalone MCP server with any compatible client (like Claude Desktop) or integrate into your existing applications.
+- **Non-Intrusive**: Designed to work without modifying your existing API call logic.
+
+## 🚀 Getting Started
+
+### Installation
+
+```bash
+npm install -g mcp-cost-tracker
+```
+
+### Running the Server
+
+Simply run the command in your terminal:
+
+```bash
+mcp-cost-tracker
+```
+
+This will start the MCP server, listening on `stdio` for requests from a compatible client.
+
+### Connecting with Claude Desktop
+
+1.  Open Claude Desktop settings.
+2.  Go to the "MCP Servers" section.
+3.  Click "Add Server" and choose "From Command".
+4.  Enter `mcp-cost-tracker` as the command.
+5.  Save and enable the server.
+
+Now you can use all the cost tracking tools directly within Claude!
+
+## 🛠️ MCP Tools
+
+`mcp-cost-tracker` provides a rich set of tools to manage your LLM costs. Here are some of the key tools available:
+
+| Tool Name | Description |
+| :--- | :--- |
+| `track_usage` | Record an API call with token counts and automatically calculate its cost. |
+| `get_summary` | Get a summary of total costs, tokens, and request counts, with filters. |
+| `get_cost_by_model` | See a cost breakdown grouped by model to identify top cost drivers. |
+| `get_daily_trend` | View daily cost trends to spot spending patterns. |
+| `set_budget` | Create or update a spending budget with alerts. |
+| `check_budget` | Check the current status of your budgets. |
+| `generate_dashboard` | Generate an interactive HTML dashboard. |
+| `lookup_pricing` | Look up pricing for any supported model. |
+| `estimate_cost` | Estimate the cost of an API call before making it. |
+| `compare_models` | Compare the cost of a workload across different models. |
+| `export_data` | Export usage data to CSV or JSON for external analysis. |
+
+For a full list of tools and their arguments, you can use the `tools/list` method from your MCP client.
+
+## 📊 Dashboard
+
+To generate the HTML dashboard, use the `generate_dashboard` tool:
+
+```
+> generate_dashboard
+```
+
+This will create a `dashboard.html` file in your `~/.mcp-cost-tracker/` directory. Open this file in your browser to see a detailed visualization of your spending.
+
+## ⚙️ Configuration
+
+By default, the database is stored at `~/.mcp-cost-tracker/costs.db`.
+
+You can specify a custom database path by setting the `MCP_COST_TRACKER_DB` environment variable:
+
+```bash
+export MCP_COST_TRACKER_DB=/path/to/your/costs.db
+mcp-cost-tracker
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss improvements.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/dist/dashboard/generator.d.ts

@@ -0,0 +1,54 @@
+import { CostDatabase } from '../storage/database.js';
+export interface DashboardData {
+    summary: {
+        total_cost: number;
+        total_input_tokens: number;
+        total_output_tokens: number;
+        total_cached_tokens: number;
+        total_requests: number;
+        avg_cost_per_request: number;
+    };
+    costByModel: Array<{
+        provider: string;
+        model: string;
+        total_cost: number;
+        total_input_tokens: number;
+        total_output_tokens: number;
+        request_count: number;
+    }>;
+    costByProvider: Array<{
+        provider: string;
+        total_cost: number;
+        total_input_tokens: number;
+        total_output_tokens: number;
+        request_count: number;
+    }>;
+    costByDay: Array<{
+        date: string;
+        total_cost: number;
+        total_tokens: number;
+        request_count: number;
+    }>;
+    costByProject: Array<{
+        project: string;
+        total_cost: number;
+        total_tokens: number;
+        request_count: number;
+    }>;
+    topExpensive: Array<{
+        timestamp: string;
+        provider: string;
+        model: string;
+        total_cost: number;
+        total_tokens: number;
+        description: string;
+    }>;
+    generatedAt: string;
+}
+export declare function collectDashboardData(db: CostDatabase, days?: number): DashboardData;
+export declare function generateDashboardHTML(data: DashboardData): string;
+/**
+ * Generate a Markdown text report (for terminal / MCP response).
+ */
+export declare function generateTextReport(data: DashboardData): string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/dashboard/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/dashboard/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;QACvB,oBAAoB,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,WAAW,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,cAAc,EAAE,KAAK,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,aAAa,EAAE,KAAK,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,YAAY,EAAE,KAAK,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,GAAE,MAAW,GAAG,aAAa,CAiBvF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA6ejE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA6D9D"}