内容
# 轻量级图表MCP
[](https://pypi.org/project/lwcmcp/)
[](https://python.org)
[](https://trychroma.com)
[](https://modelcontextprotocol.io)
[](LICENSE)
[](https://github.com/TheFractalyst/LightWeightChartsMCP/actions/workflows/test.yml)
完整的TradingView轻量级图表参考文档MCP服务器，包含6种工具，用于语义搜索、JS/TS代码验证和模板生成。
[快速开始](#一键启动) |
[工具](#工具) |
[配置](#配置) |
[开发](#开发)
---
```bash
pip install lwcmcp
lwcmcp
```
就这么简单。首次运行时，服务器会自动从预装的JSON数据构建ChromaDB向量存储（需要30-60秒来下载嵌入模型并建立索引）。后续运行立即启动。
**您将获得：**
- 6种MCP工具，用于轻量级图表文档查找、JS/TS代码验证和模板生成
- 约1617个条目索引在本地ChromaDB向量存储中（100%离线）
- 亚毫秒级热缓存，用于优先级查找
- 基于正则表达式的JS/TS验证器（无需Node.js运行时）
- 与Claude Desktop、Cursor、Windsurf、OpenCode和任何MCP客户端兼容
**您需要：**
- Python 3.10+
- 任意MCP兼容的AI客户端
---
## 功能
- **6种工具**：查找、搜索、浏览、验证、修复、搭建
- **1种资源**：`lwc://stats`
- **100%本地**：ChromaDB向量存储，运行时无需网络调用
- **快速**：热缓存实现即时查找，名称索引实现模糊匹配，语义搜索（预热）
- **5种版本**：3.8、4.0、4.1、4.2、5.0，包含教程和框架集成
- **验证器**：基于正则表达式的JS/TS验证（无需Node.js运行时）
- **7种模板**：基本图表、实时更新、React集成、Vue集成、Web组件、自定义样式、多系列
- **版本过滤**：每种工具都接受`version`参数来过滤LWC版本
- **生产就绪**：健康端点、熔断器、错误掩蔽、响应限制、响应缓存中间件
## 覆盖范围
- LWC API：函数、接口、枚举、类型别名、变量（所有5种版本）
- 指南：入门、系列类型、价格规模、时间规模、时区、插件、迁移、Android、iOS、发行说明
- 教程：自定义、辅助功能、React、Vue.js、Web组件、操作方法、演示
- 总共：约1617个条目，涵盖5种版本 + 教程
- ChromaDB：所有条目都已索引（JSON = ChromaDB，无重复数据丢失）
## 安装
```bash
pip install lwcmcp
```
或从源码安装：
```bash
git clone https://github.com/TheFractalyst/LightWeightChartsMCP.git
cd LightWeightChartsMCP
pip install -e ".[dev]"
```
## 运行服务器
```bash
# 标准输入输出（适用于Claude、Cursor、opencode等MCP客户端）
lwcmcp
# SSE（HTTP）
lwcmcp --transport sse --port 8080
# 手动构建ChromaDB（否则在首次运行时自动构建）
lwcmcp build
```
## MCP客户端配置
### Claude Desktop
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）
或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"lightweightchartsmcp": {
"command": "lwcmcp",
"transport": "stdio"
}
}
}
```
### Cursor / Windsurf / OpenCode
将以下内容添加到项目的 `.mcp.json` 或全局MCP配置中：
```json
{
"mcpServers": {
"lightweightchartsmcp": {
"command": "lwcmcp",
"transport": "stdio"
}
}
}
```
### SSE（HTTP）
```bash
lwcmcp --transport sse --port 8080
```
连接到 `http://localhost:8080`。
## 工具
```
+--------------+-----------+------------------------------------------+
| 工具 | 类型 | 描述 |
+--------------+-----------+------------------------------------------+
| lwc_lookup | 只读 | 精确名称查找，模糊备用 |
| lwc_search | 只读 | 跨所有条目的语义搜索 |
| lwc_browse | 只读 | 列出命名空间成员 |
| lwc_validate | 读写 | 验证轻量级图表的JS/TS代码 |
| lwc_repair | 读写 | 修复轻量级图表的常见问题 |
| lwc_scaffold | 读写 | 生成图表模板（7种） |
+--------------+-----------+------------------------------------------+
```
```
+----------------+----------------------------------------------------+
| 工具 | 签名 |
+----------------+----------------------------------------------------+
| lwc_lookup | (名称, 类型?, 版本?) |
| lwc_search | (查询, 类别?, 命名空间?, 版本?, 结果数?) |
| lwc_browse | (命名空间, 类别?, 样式?, 版本?) |
| lwc_validate | (代码?, 文件路径?, 文件内容?, 版本?) |
| lwc_repair | (代码, 上下文, 版本?) |
| lwc_scaffold | (类型, 名称, 描述?, 版本?) |
+----------------+----------------------------------------------------+
```
### 版本过滤
每种工具都接受一个可选的`version`参数：
- `"3.8"`、`"4.0"`、`"4.1"`、`"4.2"`、`"5.0"` - 过滤到特定版本
- `None`（默认）- 跨所有版本搜索（优先使用最新的5.0）
## 配置
```
+------------------------+------------------+--------------------------------------------+
| 环境变量 | 默认值 | 描述 |
+------------------------+------------------+--------------------------------------------+
| TRANSPORT | stdio | 传输方式：stdio或sse |
| PORT | 8080 | SSE传输端口 |
| LWC_DB_PATH | ~/.lwc_mcp/db | ChromaDB路径 |
| LWC_COLLECTION | lwc_reference | ChromaDB集合名称 |
| LWC_EMBED_MODEL | all-MiniLM-L6-v2 | 句子转换器模型 |
| LWC_MAX_RESULTS | 100 | 返回的最大结果数 |
| VALIDATION_CACHE_TTL | 300 | 验证缓存TTL（秒） |
| VALIDATION_CACHE_SIZE | 500 | 验证缓存最大条目数 |
| LWC_INDEX_BATCH_SIZE | 25 | 索引批次大小 |
| LAZY_MODEL | （空） | 设置为1/true以延迟加载模型 |
| LOG_DIR | ~/.lwc_mcp/logs | 日志目录（SSE传输） |
| LOG_LEVEL | INFO | 日志级别 |
+------------------------+------------------+--------------------------------------------+
```
## 命名空间
### API命名空间
```
+----------------+----------------------------------------------+
| 命名空间 | 描述 |
+----------------+----------------------------------------------+
| enumerations | 枚举（LineStyle, CrosshairMode等） |
| functions | 函数（createChart, addSeries等） |
| interfaces | 接口（IChartApi, ISeriesApi等） |
| type-aliases | 类型别名（SeriesType, Time等） |
| variables | 变量和常量 |
+----------------+----------------------------------------------+
```
### 指南命名空间
```
+------------------+------------------------------------------+
| 命名空间 | 描述 |
+------------------+------------------------------------------+
| getting-started | 入门指南 |
| android | Android平台集成 |
| ios | iOS平台集成 |
| price-scale | 价格规模配置 |
| release-notes | 版本发行说明 |
| series-types | 系列类型（candlestick, line等） |
| time-scale | 时间规模配置 |
| time-zones | 时区处理 |
| migrations | 版本迁移指南 |
| plugins | 插件系统（v4.1+） |
+------------------+------------------------------------------+
```
### 教程命名空间
```
+----------------+----------------------------------------------+
| 命名空间 | 描述 |
+----------------+----------------------------------------------+
| customization | 图表自定义教程 |
| a11y | 无障碍教程 |
| react | React框架集成 |
| vuejs | Vue.js框架集成 |
| webcomponents | Web组件集成 |
| how-to | 操作方法指南 |
| demos | 演示应用程序 |
+----------------+----------------------------------------------+
```
## 搭建模板（7种）
```
+--------------------+----------------------------------------------+
| 类型 | 描述 |
+--------------------+----------------------------------------------+
| basic_chart | 基本图表，带有createChart + setData |
| realtime_updates | 实时数据流，带有series.update |
| react_integration | React组件，带有useRef + useEffect |
| vue_integration | Vue.js组件，带有ref |
| web_components | Web组件自定义元素包装 |
| custom_styling | 自定义图表和系列选项/样式 |
| multi_series | 多系列（candlestick + volume） |
+--------------------+----------------------------------------------+
```
## 开发
```bash
ruff check . --line-length 120 # 校验
pytest tests/ -v # 测试
```
## 架构
- **FastMCP 3.4**，带有文件系统提供程序，实现自动发现
- **ChromaDB** 向量存储（余弦，all-MiniLM-L6-v2，384维）
- 3种可组合的生命周期：db | model | cache
- 首次运行时自动从预装的JSON数据构建ChromaDB
- 响应缓存中间件（查找/浏览 1小时，搜索 5分钟）
- 响应限制中间件（80KB上限）
- 验证器和ChromaDB上的熔断器
- 快速查找的热缓存
- 错误掩蔽（不会泄露内部细节）
- `/health`健康端点
## 数据库
- 约1617个条目，涵盖5个版本（3.8、4.0、4.1、4.2、5.0）+ 教程
- 首次运行时从预装的JSON数据自动构建（1.5MB）
- 存储在 `~/.lwc_mcp/db`（在项目更新后仍然存在）
要重建数据库：
```bash
lwcmcp build
```
## 数据管道
- `pipeline/scrape_lwc.py` - 直接HTTP抓取器，用于轻量级图表文档站点地图（github.io，无需ScraperAPI）
- `pipeline/merge_and_index.py` - 合并 + 索引到ChromaDB
### 从TradingView重新抓取
```bash
pip install -e ".[pipeline]"
python pipeline/scrape_lwc.py
python pipeline/merge_and_index.py --reset
```
## 技术栈
- **FastMCP 3.4** - MCP服务器框架，带有文件系统提供程序，实现自动发现
- **ChromaDB** - 用于语义搜索的本地向量数据库
- **SentenceTransformers** - `all-MiniLM-L6-v2` 嵌入模型（384维）
- **RapidFuzz** - 用于名称查找的模糊字符串匹配
- **Loguru** - 带有每日轮换的Structured logging（SSE模式）
## 链接
- [fractalyst.dev](https://fractalyst.dev/) - 作者首页
- [TradingView](https://www.tradingview.com/u/Fractalyst/#published-scripts) - 公共PineScript指标
- [@TheFractalyst](https://x.com/TheFractalyst) - X / Twitter
## 许可证
MIT - 见 [LICENSE](LICENSE)
