Metadata-Version: 2.4
Name: mcp-nacos-helper
Version: 1.0.3
Summary: 基于 FastMCP 的 Nacos 配置读取与服务状态分析工具。
Author-email: mengbi <mengbi1014@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mengbi-super/MCP-TOOLS
Project-URL: Documentation, https://github.com/mengbi-super/MCP-TOOLS/blob/main/packages/nacos_helper/README.md
Project-URL: Repository, https://github.com/mengbi-super/MCP-TOOLS
Project-URL: Issues, https://github.com/mengbi-super/MCP-TOOLS/issues
Keywords: mcp,nacos,fastmcp,config
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"

# Nacos MCP 使用指南

一个基于 FastMCP 的 Model Context Protocol (MCP) 工具，用于读取 Nacos 配置、查看历史版本、对比变更以及检查服务注册状态，兼容 Nacos 2.4.x。

---

## 📋 目录

1. [功能特点](#功能特点)
2. [快速开始](#快速开始)
3. [在 Cursor 中集成](#在-cursor-中集成)
4. [工具功能](#工具功能)
5. [使用示例](#使用示例)
6. [常见问题](#常见问题)

---

## 功能特点

### 核心能力

- 📄 **配置读取**：按 Data ID 获取单个配置或批量读取多个配置
- 🧭 **历史追溯**：列出配置历史、获取详情、自动对比最近两版
- ✅ **服务状态检查**：查看服务实例、健康状态、注册情况
- 🧩 **上下文汇总**：一次性聚合配置、历史与服务状态信息
- 🔐 **鉴权支持**：支持用户名密码登录，自动管理 token
- 🧰 **兼容 Nacos 2.4.x**：对接口版本差异做兜底处理

### 配置灵活性

工具支持多种配置方式，按优先级自动选择：

1. **方法参数**（调用时直接传入）
2. **环境变量**（Cursor MCP 配置或系统环境变量）
3. **默认值**（工具内置）

---

## 快速开始

### 环境准备

#### Python 版本要求

- **Python 3.8 或更高版本**（推荐 Python 3.9+）
- 支持 Windows、Linux、Mac 操作系统

#### 检查 Python 环境

```bash
# 检查 Python 版本
python --version
# 或
py --version
```

#### 检查 pip 是否可用

```bash
# 检查 pip 版本
pip --version
# 或
py -m pip --version
```

### 安装

#### 从 PyPI 安装（默认）

```bash
pip install mcp-nacos-helper
```

#### 使用国内镜像源（可选）

```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcp-nacos-helper
```

---

## 在 Cursor 中集成

示例配置见：`configs/cursor-mcp-config-example.json`

推荐在 `env` 中补充：

- `PYTHONUTF8=1`
- `PYTHONIOENCODING=utf-8`

**PyPI 安装模式示例**：

```json
{
  "mcpServers": {
    "nacos-helper-pypi": {
      "command": "py",
      "args": [
        "-m",
        "mcp_services.nacos.tool"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONUTF8": "1",
        "PYTHONIOENCODING": "utf-8",
        "NACOS_SERVER_ADDR": "http://127.0.0.1:8848",
        "NACOS_NAMESPACE": "sae-dev",
        "NACOS_GROUP": "DEFAULT_GROUP",
        "NACOS_USERNAME": "nacos",
        "NACOS_PASSWORD": "nacos",
        "NACOS_TIMEOUT": "5",
        "NACOS_DATA_IDS": "application.yml,bootstrap.yml",
        "NACOS_REGISTRY_NAMESPACE": "sae-registry"
      }
    }
  }
}
```

**说明**：
- `NACOS_NAMESPACE`：配置读取命名空间
- `NACOS_REGISTRY_NAMESPACE`：服务注册查询命名空间（可选）
- `PYTHONUTF8`/`PYTHONIOENCODING`：避免中文乱码

---

## 工具功能

工具提供以下能力（文字说明）：

- **配置读取**：读取单个或多个配置
- **历史追溯**：列出历史、获取详情、对比最近两版
- **服务状态检查**：查看实例与健康状态
- **上下文汇总**：聚合配置、历史、服务状态

---

## 使用示例

示例均为“自然语言调用”，适合在 Cursor 中直接提问：

```
读取 cdc-major-disease-service.yml 的配置
对比 cdc-major-disease-service.yml 最近两版历史
检查 CDC-MAJOR-DISEASE-SERVICE 是否已注册
```

---

## 常见问题

### 1) 历史接口提示需要 nid

工具已自动处理，直接使用“获取最新历史”或“对比最近两版”的能力即可。

### 2) 历史返回 0，但控制台有数据

多为 namespace 参数或接口版本差异导致，请检查：

- `NACOS_NAMESPACE`
- `NACOS_REGISTRY_NAMESPACE`

### 3) 中文输出乱码

在环境变量中添加：

- `PYTHONUTF8=1`
- `PYTHONIOENCODING=utf-8`
