micro-app-mcp 0.1.0__tar.gz

micro_app_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Xu
+
+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.

micro_app_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: micro-app-mcp
+Version: 0.1.0
+Summary: MCP Server for micro-app knowledge base
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp<2.0,>=0.1.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: langchain>=0.2.0
+Requires-Dist: langchain-community>=0.2.0
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: huggingface-hub>=0.20.0
+Requires-Dist: sentence-transformers>=2.0.0
+Requires-Dist: uvicorn>=0.27.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: PyGithub>=1.58.0
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: html2text>=2020.1.16
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# Micro-App MCP Server
+
+MCP Server for micro-app knowledge base
+
+## 项目简介
+
+该项目是一个专门用于查询 micro-app 微前端框架知识库的 MCP Server。它整合了 GitHub 源码和在线文档内容，支持语义检索。当用户输入 `/micro` 时，LLM 会先检索知识库再回答问题。
+
+## 核心功能
+
+- **数据采集**: 自动从 GitHub 获取源码，从在线文档站点获取文档内容
+- **知识向量化**: 将采集的文本内容进行分块、向量化存储
+- **语义检索**: 提供基于向量相似度的语义检索能力
+- **MCP 协议集成**: 暴露标准 MCP 工具接口，支持 Trae AI Agent 和 VSCode 智能体
+
+## 技术栈
+
+- **MCP 框架**: FastMCP
+- **HTTP 框架**: FastAPI
+- **依赖管理**: uv
+- **LLM 框架**: LangChain
+- **向量数据库**: ChromaDB
+- **文档采集**: LangChain AsyncChromiumLoader
+- **源码采集**: PyGithub
+
+## 用法
+### 方法一：PyPI包方式
+
+#### 安装PyPI包
+
+```bash
+pip install micro-app-mcp
+
+# 运行依赖：DocsLoader 用 Playwright 爬取文档网站，Playwright 需要浏览器（Chromium）才能渲染页面
+python -m playwright install chromium
+```
+
+#### 运行
+
+```bash
+micro-app-mcp
+```
+
+### 方法二：源码方式
+
+#### 安装源码
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd micro-app-mcp
+
+# 安装依赖
+uv sync
+
+uv run python -m playwright install chromium
+
+# 将本项目作为 editable 包安装，解决项目中自身包路径问题
+uv run pip install -e .
+```
+
+#### 环境变量配置
+
+复制 `.env.example` 文件为 `.env` 并根据需要修改配置：
+
+```bash
+cp .env.example .env
+```
+
+主要配置项：
+
+- `EMBEDDING_MODEL`: 向量化模型类型，目前只支持 `local`
+- `EMBEDDING_MODEL_NAME`: 本地向量化模型名称，默认 `BAAI/bge-small-zh-v1.5`
+- `EMBEDDING_LAZY_LOAD`: 是否启用懒加载，默认 `true`（推荐开启，可减少启动内存占用）
+- `GITHUB_TOKEN`: GitHub API Token，可选，用于提高 API 限流
+- `DATA_DIR`: 数据存储路径，默认 `~/work_space/tmp/micro_app_mcp`
+- `CACHE_DURATION_HOURS`: 智能缓存配置，默认 24 小时
+- `DISPLAY_TIMEZONE`: 状态展示时区，默认 `Asia/Shanghai`
+
+#### 本地服务器直接运行
+
+```bash
+uv run micro-app-mcp
+```
+
+#### MCP 服务器配置与运行（适合宿主项目配合开发调试）
+
+```json
+{
+  "mcpServers": {
+    "micro-app-mcp": {
+      "command": "uv",
+      "args": [
+        "run",
+        "python",
+        "src/micro_app_mcp/main.py"
+      ],
+      "cwd": "/Users/twonian/work_space/trinapower/ai_agent_service/micro-app-mcp",
+      "env": {
+        "DATA_DIR": "~/work_space/tmp/micro_app_mcp",
+        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
+      }
+    }
+  }
+}
+```
+
+#### 测试
+
+```bash
+# 运行测试
+uv run pytest
+```
+
+### 方法三：IDE智能体方式
+
+#### 安装依赖
+
+```bash
+uvx --from micro-app-mcp python -m playwright install chromium
+```
+
+#### MCP 服务器配置
+
+###### 方法一：在 Trae AI Agent 中配置 MCP 服务器
+
+- 打开 Trae AI Agent 配置文件（`config.json`）
+- 添加以下内容：
+
+```json
+{
+  "mcpServers": {
+    "micro-app-knowledge": {
+      "command": "uvx",
+      "args": ["--from", "micro-app-mcp", "micro-app-mcp"],
+      "env": {
+        "DATA_DIR": "~/work_space/tmp/micro_app_mcp"
+      }
+    }
+  }
+}
+```
+
+###### 方法二：在 VSCode 中配置 MCP 服务器
+
+- 打开 VSCode 智能体配置文件（`mcp.json`）
+- 添加以下内容：
+
+```json
+{
+  "mcpServers": {
+    "micro-app-knowledge": {
+      "command": "uvx",
+      "args": ["--from", "micro-app-mcp", "micro-app-mcp"],
+      "env": {
+        "DATA_DIR": "~/work_space/tmp/micro_app_mcp"
+      }
+    }
+  }
+}
+```
+
+#### LLM调用MCP工具内在逻辑
+
+当用户输入以 `/micro` 开头或包含 `/micro` 的消息时，会优先调用统一入口工具 `micro_app_command`，再按意图分发：
+
+- 状态类请求：调用 `get_knowledge_base_status`
+- 更新类请求：调用 `update_knowledge_base`
+- 其他请求：调用 `search_micro_app_knowledge`
+
+推荐的工具编排方式：
+
+1. 先调用 `get_knowledge_base_status`（只读状态）
+2. 当 `is_stale=true` 或用户明确要求更新时，再调用 `update_knowledge_base`
+3. 最后调用 `search_micro_app_knowledge` 进行检索
+
+可用 MCP 工具：
+
+- `get_knowledge_base_status`: 返回本地时区的 `last_updated`/`next_recommended_update_at`，以及对应 UTC 字段、`is_stale`、`should_skip_update`、`document_count` 等状态信息
+- `update_knowledge_base(force=False)`: 显式更新知识库（写操作）
+- `search_micro_app_knowledge(query, top_k=15)`: 语义检索（只读）
+
+#### 示例
+
+1. `/micro 获取知识库状态`
+2. `/micro 强制更新知识库 force=true`
+3. `/micro <你的检索问题>`
+
+## 项目结构
+
+```
+micro-app-mcp/
+├── pyproject.toml                 # 项目配置
+├── uv.lock                        # 依赖锁定
+├── README.md                      # 项目说明
+├── src/
+│   └── micro_app_mcp/
+│       ├── __init__.py
+│       ├── main.py                # FastMCP 入口
+│       ├── config.py              # 配置管理
+│       ├── mcp/
+│       │   ├── __init__.py
+│       │   ├── server.py          # MCP Server 定义
+│       │   └── tools.py           # MCP 工具实现
+│       ├── knowledge/
+│       │   ├── __init__.py
+│       │   ├── base.py            # 知识处理基类
+│       │   ├── github_loader.py   # GitHub 源码采集
+│       │   ├── docs_loader.py     # 文档采集 (Playwright)
+│       │   ├── text_splitter.py   # 文本分块
+│       │   └── vectorizer.py      # 向量化处理
+│       ├── storage/
+│       │   ├── __init__.py
+│       │   ├── vector_store.py    # ChromaDB 封装
+│       │   └── metadata.py        # 元数据管理
+│       └── utils/
+│           ├── __init__.py
+│           └── logger.py          # 日志工具
+├── tests/
+│   ├── __init__.py
+│   ├── test_tools.py
+│   └── test_knowledge.py
+└── .env.example                   # 环境变量示例
+```
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT

micro_app_mcp-0.1.0/README.md

@@ -0,0 +1,232 @@
+# Micro-App MCP Server
+
+MCP Server for micro-app knowledge base
+
+## 项目简介
+
+该项目是一个专门用于查询 micro-app 微前端框架知识库的 MCP Server。它整合了 GitHub 源码和在线文档内容，支持语义检索。当用户输入 `/micro` 时，LLM 会先检索知识库再回答问题。
+
+## 核心功能
+
+- **数据采集**: 自动从 GitHub 获取源码，从在线文档站点获取文档内容
+- **知识向量化**: 将采集的文本内容进行分块、向量化存储
+- **语义检索**: 提供基于向量相似度的语义检索能力
+- **MCP 协议集成**: 暴露标准 MCP 工具接口，支持 Trae AI Agent 和 VSCode 智能体
+
+## 技术栈
+
+- **MCP 框架**: FastMCP
+- **HTTP 框架**: FastAPI
+- **依赖管理**: uv
+- **LLM 框架**: LangChain
+- **向量数据库**: ChromaDB
+- **文档采集**: LangChain AsyncChromiumLoader
+- **源码采集**: PyGithub
+
+## 用法
+### 方法一：PyPI包方式
+
+#### 安装PyPI包
+
+```bash
+pip install micro-app-mcp
+
+# 运行依赖：DocsLoader 用 Playwright 爬取文档网站，Playwright 需要浏览器（Chromium）才能渲染页面
+python -m playwright install chromium
+```
+
+#### 运行
+
+```bash
+micro-app-mcp
+```
+
+### 方法二：源码方式
+
+#### 安装源码
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd micro-app-mcp
+
+# 安装依赖
+uv sync
+
+uv run python -m playwright install chromium
+
+# 将本项目作为 editable 包安装，解决项目中自身包路径问题
+uv run pip install -e .
+```
+
+#### 环境变量配置
+
+复制 `.env.example` 文件为 `.env` 并根据需要修改配置：
+
+```bash
+cp .env.example .env
+```
+
+主要配置项：
+
+- `EMBEDDING_MODEL`: 向量化模型类型，目前只支持 `local`
+- `EMBEDDING_MODEL_NAME`: 本地向量化模型名称，默认 `BAAI/bge-small-zh-v1.5`
+- `EMBEDDING_LAZY_LOAD`: 是否启用懒加载，默认 `true`（推荐开启，可减少启动内存占用）
+- `GITHUB_TOKEN`: GitHub API Token，可选，用于提高 API 限流
+- `DATA_DIR`: 数据存储路径，默认 `~/work_space/tmp/micro_app_mcp`
+- `CACHE_DURATION_HOURS`: 智能缓存配置，默认 24 小时
+- `DISPLAY_TIMEZONE`: 状态展示时区，默认 `Asia/Shanghai`
+
+#### 本地服务器直接运行
+
+```bash
+uv run micro-app-mcp
+```
+
+#### MCP 服务器配置与运行（适合宿主项目配合开发调试）
+
+```json
+{
+  "mcpServers": {
+    "micro-app-mcp": {
+      "command": "uv",
+      "args": [
+        "run",
+        "python",
+        "src/micro_app_mcp/main.py"
+      ],
+      "cwd": "/Users/twonian/work_space/trinapower/ai_agent_service/micro-app-mcp",
+      "env": {
+        "DATA_DIR": "~/work_space/tmp/micro_app_mcp",
+        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
+      }
+    }
+  }
+}
+```
+
+#### 测试
+
+```bash
+# 运行测试
+uv run pytest
+```
+
+### 方法三：IDE智能体方式
+
+#### 安装依赖
+
+```bash
+uvx --from micro-app-mcp python -m playwright install chromium
+```
+
+#### MCP 服务器配置
+
+###### 方法一：在 Trae AI Agent 中配置 MCP 服务器
+
+- 打开 Trae AI Agent 配置文件（`config.json`）
+- 添加以下内容：
+
+```json
+{
+  "mcpServers": {
+    "micro-app-knowledge": {
+      "command": "uvx",
+      "args": ["--from", "micro-app-mcp", "micro-app-mcp"],
+      "env": {
+        "DATA_DIR": "~/work_space/tmp/micro_app_mcp"
+      }
+    }
+  }
+}
+```
+
+###### 方法二：在 VSCode 中配置 MCP 服务器
+
+- 打开 VSCode 智能体配置文件（`mcp.json`）
+- 添加以下内容：
+
+```json
+{
+  "mcpServers": {
+    "micro-app-knowledge": {
+      "command": "uvx",
+      "args": ["--from", "micro-app-mcp", "micro-app-mcp"],
+      "env": {
+        "DATA_DIR": "~/work_space/tmp/micro_app_mcp"
+      }
+    }
+  }
+}
+```
+
+#### LLM调用MCP工具内在逻辑
+
+当用户输入以 `/micro` 开头或包含 `/micro` 的消息时，会优先调用统一入口工具 `micro_app_command`，再按意图分发：
+
+- 状态类请求：调用 `get_knowledge_base_status`
+- 更新类请求：调用 `update_knowledge_base`
+- 其他请求：调用 `search_micro_app_knowledge`
+
+推荐的工具编排方式：
+
+1. 先调用 `get_knowledge_base_status`（只读状态）
+2. 当 `is_stale=true` 或用户明确要求更新时，再调用 `update_knowledge_base`
+3. 最后调用 `search_micro_app_knowledge` 进行检索
+
+可用 MCP 工具：
+
+- `get_knowledge_base_status`: 返回本地时区的 `last_updated`/`next_recommended_update_at`，以及对应 UTC 字段、`is_stale`、`should_skip_update`、`document_count` 等状态信息
+- `update_knowledge_base(force=False)`: 显式更新知识库（写操作）
+- `search_micro_app_knowledge(query, top_k=15)`: 语义检索（只读）
+
+#### 示例
+
+1. `/micro 获取知识库状态`
+2. `/micro 强制更新知识库 force=true`
+3. `/micro <你的检索问题>`
+
+## 项目结构
+
+```
+micro-app-mcp/
+├── pyproject.toml                 # 项目配置
+├── uv.lock                        # 依赖锁定
+├── README.md                      # 项目说明
+├── src/
+│   └── micro_app_mcp/
+│       ├── __init__.py
+│       ├── main.py                # FastMCP 入口
+│       ├── config.py              # 配置管理
+│       ├── mcp/
+│       │   ├── __init__.py
+│       │   ├── server.py          # MCP Server 定义
+│       │   └── tools.py           # MCP 工具实现
+│       ├── knowledge/
+│       │   ├── __init__.py
+│       │   ├── base.py            # 知识处理基类
+│       │   ├── github_loader.py   # GitHub 源码采集
+│       │   ├── docs_loader.py     # 文档采集 (Playwright)
+│       │   ├── text_splitter.py   # 文本分块
+│       │   └── vectorizer.py      # 向量化处理
+│       ├── storage/
+│       │   ├── __init__.py
+│       │   ├── vector_store.py    # ChromaDB 封装
+│       │   └── metadata.py        # 元数据管理
+│       └── utils/
+│           ├── __init__.py
+│           └── logger.py          # 日志工具
+├── tests/
+│   ├── __init__.py
+│   ├── test_tools.py
+│   └── test_knowledge.py
+└── .env.example                   # 环境变量示例
+```
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT

micro_app_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "micro-app-mcp"
+version = "0.1.0"
+description = "MCP Server for micro-app knowledge base"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=0.1.0,<2.0",
+    "fastapi>=0.109.0",
+    "langchain>=0.2.0",
+    "langchain-community>=0.2.0",
+    "chromadb>=0.4.0",
+    "playwright>=1.40.0",
+    "huggingface-hub>=0.20.0",
+    "sentence-transformers>=2.0.0",
+    "uvicorn>=0.27.0",
+    "pydantic>=2.5.0",
+    "python-dotenv>=1.0.0",
+    "PyGithub>=1.58.0",
+    "mcp>=1.26.0",
+    "html2text>=2020.1.16",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0", "pytest-asyncio>=0.23.0"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = { "" = "src" } # 告诉 setuptools：根包在 src/ 下，决定 wheel 包的目录结构没有包含 src 目录本身
+
+[tool.setuptools.packages.find]
+where = ["src"]             # 在 src/ 目录下查找包，有配置 package-dir，此处可省略
+include = ["micro_app_mcp"] # 只包含 micro_app_mcp 包
+
+[project.scripts]
+micro-app-mcp = "micro_app_mcp.main:main"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"         # 自动检测异步测试
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

micro_app_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

micro_app_mcp-0.1.0/src/micro_app_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Micro-App MCP Server"""
+
+__version__ = "0.1.0"

micro_app_mcp-0.1.0/src/micro_app_mcp/app/__init__.py

@@ -0,0 +1 @@
+"""MCP 模块"""

micro_app_mcp-0.1.0/src/micro_app_mcp/app/server.py

@@ -0,0 +1,109 @@
+"""FastMCP Server 定义"""
+
+from fastmcp import FastMCP
+from micro_app_mcp.app.tools import (
+    get_knowledge_base_status as status_tool,
+    search_micro_app_knowledge as search_tool,
+    update_knowledge_base as update_tool
+)
+
+# 创建 FastMCP 实例，包含 /micro 触发机制
+mcp = FastMCP(
+    "micro-app-knowledge-server",
+    instructions=(
+        "当用户消息以 /micro 开头或包含 /micro 时，优先调用 micro_app_command 工具。"
+        "micro_app_command 会自动分发："
+        "1) 状态类请求 -> get_knowledge_base_status；"
+        "2) 更新/同步类请求 -> update_knowledge_base；"
+        "3) 其他请求 -> search_micro_app_knowledge。"
+    )
+)
+
+
+def _normalize_micro_command(command: str) -> str:
+    """移除 /micro 前缀，得到实际命令内容"""
+    return command.replace("/micro", "", 1).strip()
+
+
+def _is_status_command(command: str) -> bool:
+    """判断是否为状态查询命令"""
+    keywords = ("状态", "status", "更新时间", "是否过期", "过期", "stale")
+    lowered = command.lower()
+    return "get_knowledge_base_status" in lowered or any(k in lowered for k in keywords)
+
+
+def _is_update_command(command: str) -> bool:
+    """判断是否为更新命令"""
+    keywords = ("更新", "同步", "重建", "refresh", "update")
+    lowered = command.lower()
+    return "update_knowledge_base" in lowered or any(k in lowered for k in keywords)
+
+
+def _is_force_update(command: str) -> bool:
+    """判断是否要求强制更新"""
+    lowered = command.lower()
+    return "force=true" in lowered or "强制" in lowered
+
+
+@mcp.tool()
+async def micro_app_command(command: str, top_k: int = 15) -> object:
+    """
+    统一处理 /micro 命令并自动分发到对应工具。
+
+    Args:
+        command: 用户输入命令（可包含 /micro 前缀）
+        top_k: 搜索时返回结果数量
+
+    Returns:
+        状态字典或结果文本
+    """
+    normalized = _normalize_micro_command(command)
+
+    if _is_status_command(normalized):
+        return await status_tool()
+
+    if _is_update_command(normalized):
+        return await update_tool(force=_is_force_update(normalized))
+
+    query = normalized or command
+    return await search_tool(query, top_k)
+
+
+@mcp.tool()
+async def search_micro_app_knowledge(query: str, top_k: int = 15) -> str:
+    """
+    语义检索 micro-app 知识库。
+
+    Args:
+        query: 用户查询内容
+        top_k: 返回最相关的结果数量，默认 15
+
+    Returns:
+        格式化的检索结果，包含源码和文档片段
+    """
+    return await search_tool(query, top_k)
+
+
+@mcp.tool()
+async def get_knowledge_base_status() -> dict:
+    """
+    获取知识库状态。
+
+    Returns:
+        状态信息，包含更新时间、过期状态、文档数量等
+    """
+    return await status_tool()
+
+
+@mcp.tool()
+async def update_knowledge_base(force: bool = False) -> str:
+    """
+    触发知识库更新。
+    
+    Args:
+        force: 是否强制更新，强制更新会重新采集所有数据
+    
+    Returns:
+        更新结果摘要
+    """
+    return await update_tool(force)