@cyuanxv/openrouter-analytics-mcp 0.0.0-stage → 0.6.0-alpha.1

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright 2026 cyuanxv
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# OpenRouter 工作台 — Local MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+完整的个人费用分析、报告、成本实验和模型预设工具，通过 MCP stdio 在本机运行，使用 SQLite 保存记录。包含与 Sites 版相同的 28 个工具。由 cyuanxv 维护：[X / Twitter @cyuanxv](https://x.com/cyuanxv)。第三方项目，非 OpenRouter 官方产品。
+
+0.6.0-alpha.1 公开 alpha。本地版不附带网页、后台任务或自动 Telegram 发送；保留报告生成、通知认领和真实回执记录能力，不执行付费推理、充值、Key 修改或生产路由切换。
+
+## 安装（中文）
+
+需要 Node.js 22.22+（22 系列）或 24+。已测试 22.22.2、24.16.0；部分 Node 版本会向 stderr 输出 SQLite 实验性功能提示。
+
+在一个新的空目录中安装固定版本：
+
+```bash
+npm install --ignore-scripts @cyuanxv/openrouter-analytics-mcp@0.6.0-alpha.1
+```
+
+在支持本地 MCP stdio 的客户端中新增如下配置。Node 和安装文件都使用自己电脑的绝对路径。通过客户端安全环境设置填写 Key，不把真实密钥粘贴进聊天、Git 或终端命令。
+
+```json
+{
+  "mcpServers": {
+    "openrouter-analytics-mcp-local": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/install/node_modules/@cyuanxv/openrouter-analytics-mcp/dist/stdio.js"],
+      "env": {
+        "OPENROUTER_WORKBENCH_DATA_DIR": "/absolute/path/to/dedicated-private-data",
+        "OPENROUTER_MANAGEMENT_KEY": "REPLACE_IN_CLIENT_SECRET_SETTINGS"
+      }
+    }
+  }
+}
+```
+
+数据目录必须是绝对路径、专用于本工具；不要指定根目录、家目录本身或源码目录。启动时会设目录权限为 0700、数据库文件为 0600（Windows 需使用者确保 ACL 私有）。数据库文件名 `workbench.sqlite`。符号链接目录、符号链接或硬链接数据库会被拒绝。缺少目录配置、权限不足或迁移失败时启动失败，不显示配置值。
+
+先调用 `routerlens_status`：mode=local-stdio，adapter_version=0.6.0-alpha.1，version 保留共享核心版本 0.5.0。authentication_verified=false 表示没有 Sites 云端身份认证；connectivity_verified=false 表示未测试上游连接。实际账户工具成功才证明自己的 Key 可用。Key 缺失时仍能管理本地记录和访问公开模型目录，账单查询会报错。保留 routerlens_status 等工具 ID 以兼容现有调用。
+
+## 数据与运行边界
+
+- 数据在自己的 SQLite 中持久保存；账户查询会访问 OpenRouter，返回结果还受 MCP 客户端的数据政策约束。
+- 本机同一用户或具备足够文件权限的程序可能访问数据库。记录可能包含费用、请求标识、人工备注和回执，不能提交到公开仓库。
+- 停止全部实例后备份整个数据目录；升级前备份。卸载包不会删除数据库。进程收到 SIGINT/SIGTERM 或客户端关闭时会关闭数据库。
+- 电脑关闭或进程退出后不能继续运行定时任务。本地版不自动发送 Telegram；模拟回执不可当作真实发送记录。
+- ChatGPT 云端不能直接启动本机 stdio 进程。需要云端运行时继续使用 Sites 版。此包不提供公共 HTTP 入口，不使用浏览器传入的 Sites 身份头。
+
+## 从完整源码构建
+
+在完整源码包的 packages/local-mcp 中执行：
+
+```bash
+npm ci --ignore-scripts
+npm run build
+npm test
+npm pack --ignore-scripts
+```
+
+构建复用 ../../services/routerlens，不能只复制此子目录进行源码构建。生成的 `.tgz` 自带运行产物和迁移文件，用户安装后不需要完整源码树，也无需运行 build。
+
+## English
+
+A local stdio MCP server with all 28 tools from the personal Sites edition: OpenRouter cost analytics, call metadata, anomaly investigation, saved reports, experiments and versioned routing presets. Requires Node.js 22.22+ (22.x) or 24+, your own OpenRouter account and, for account queries, your own Management Key.
+
+Install the pinned alpha into an empty directory using `npm install --ignore-scripts @cyuanxv/openrouter-analytics-mcp@0.6.0-alpha.1`. Configure a local MCP client to run the installed dist/stdio.js with an absolute Node.js path. Set OPENROUTER_WORKBENCH_DATA_DIR to a dedicated absolute private directory; provide OPENROUTER_MANAGEMENT_KEY through client secret settings. You can also install a downloaded release tarball with npm.
+
+SQLite records survive process restarts and package removal. Back up the data directory while all instances are stopped. There is no dashboard, HTTP listener, Sites identity, built-in scheduler or automatic Telegram delivery. This is not a ChatGPT cloud connector. No paid inference, key writes or production routing changes are performed. Returned data is also subject to your MCP client's policies.
+
+Public alpha; check the repository for the current Registry listing and verification status. Apache-2.0; independent of OpenRouter.
+
+## Release links / 发布链接
+
+安装包、源码与登记标识：
+
+- Repository : https://github.com/cyuanxv/openrouter-analytics-mcp
+- npm : https://www.npmjs.com/package/@cyuanxv/openrouter-analytics-mcp
+- MCP Registry name : `io.github.cyuanxv/openrouter-analytics-mcp`
+- CLI: `openrouter-analytics-mcp`