Metadata-Version: 2.4
Name: momcp-tui
Version: 0.1.3
Summary: A TUI-based multi-MCP tool orchestrator written in Python.
Author-email: AndyJin <2358155969@qq.com>
Project-URL: Homepage, https://mcp.andyjin.website
Keywords: mcp,tui,llm,tool-orchestrator
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.76.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Requires-Dist: mcp>=1.0.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: mcp-weather-server>=0.1.0
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# MoMCP-TUI

<div align="center">

**智能终端助手 · MCP 工具编排器 · 大模型统一入口**

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-pending-yellow.svg)](https://pypi.org/project/momcp-tui/)

</div>

---

## 📖 产品简介

MoMCP-TUI 是一款运行在终端的智能助手，通过统一的聊天界面，让您能够：

- 💬 **与主流大模型对话** —— 支持 OpenAI、DeepSeek、通义千问、Kimi 等
- 🔧 **调用 MCP 工具完成任务** —— 文件操作、代码编辑、联网搜索（百度 AI）
- 🎨 **优雅的 TUI 交互体验** —— 气泡式对话、流式输出、思考过程可视化

您只需在终端中输入自然语言指令，系统会自动判断是否需要调用工具，并返回结构化的结果。

---

## ✨ 核心特性

### 🤖 多模型支持
内置多家主流大模型预设配置，一键切换：
- **OpenAI**: `gpt-4.1-mini`, `gpt-4.1`
- **DeepSeek**: `deepseek-chat`, `deepseek-reasoner`
- **通义千问**: `qwen-plus`, `qwen-turbo`, `qwen-max`
- **Kimi**: `kimi-k2-turbo-preview`, `kimi-k2-0711-preview`

### 🛠️ MCP 工具集成
- **本地文件操作**：安全白名单机制，支持目录浏览、文件读写、删除
- **代码编辑能力**：文本替换、整文件写入，支持多种编程语言
- **联网搜索**：集成百度千帆 AI Search，获取实时信息

### 🎯 智能决策
基于 LLM 的自主规划能力，自动选择最合适的工具组合，无需手动指定。

---

## 🚀 快速开始

### 环境要求

- **操作系统**: Windows / macOS / Linux
- **Python 版本**: 3.10 或更高
- **推荐方式**: 使用 Conda 创建独立环境

```bash
# 创建 Conda 环境
conda create -n momcp python=3.10
conda activate momcp
```

### 安装方式

```bash
pip install momcp-tui
```

### 启动程序

```bash
momcp-tui
```

首次启动会提示设置用户名（显示在您的消息气泡上）。

---

## ⚙️ 配置说明

### 1. 配置大模型 API Key

系统采用"系列绑定"策略：同一系列的所有模型共用一个 API Key。

```text
# 查看可用模型列表
/model list

# 切换到目标模型（首次会提示输入 API Key）
/model set deepseek-chat

# 查看当前模型状态
/model

# 手动设置 API Key
/api_key set YOUR_API_KEY
```

**支持的模型系列**：
| 厂商 | 模型示例 | 文档链接 |
|------|----------|----------|
| OpenAI | gpt-4.1-mini | https://platform.openai.com/ |
| DeepSeek | deepseek-chat | https://platform.deepseek.com/ |
| 通义千问 | qwen-plus | https://dashscope.aliyun.com/ |
| Kimi | kimi-k2-turbo | https://platform.moonshot.cn/ |

### 2. 配置百度搜索（可选）

如需联网搜索功能，需配置百度千帆 Token：

```text
# 查看百度搜索配置状态
/web status

# 设置 Token（每日免费额度，上限 100 次）
/web set YOUR_BAIDU_TOKEN
```

> 💡 **获取 Token**: 登录 [百度千帆控制台](https://console.bce.baidu.com/qianfan/ais/console/apiKey) 创建 API Key

### 3. 管理文件访问白名单

为保护系统安全，文件操作采用"根目录 + 白名单"机制：

```text
# 查看当前白名单
/allow list

# 添加路径到白名单（自动转为绝对路径）
/allow add ~/Documents/Project

# 重启后生效
momcp-tui
```

---

## 💡 使用指南

### 基础对话

直接在输入框中输入问题，按 Enter 发送：

```
今天上海的天气如何？
帮我总结一下 Python 异步编程的最佳实践
创建一个学习计划，包含每天的任务清单
```

### 工具调用示例

系统会自动识别意图并调用相应工具：

**📁 文件操作**
```
在当前目录创建一个 notes.md 文件，记录今天的待办事项
读取 src/main.py 文件，分析其中的函数结构
把 config.json 中的日志级别从 info 改为 debug
```

**💻 代码编辑**
```
在项目根目录下找出所有使用 requests 的地方
帮我重构这个函数，添加错误处理逻辑
在 utils.py 中添加一个日期格式化工具函数
```

**🔍 联网搜索**
```
搜索最近一周关于养老金改革的新闻，总结 5 个要点
帮我查一下特斯拉最新的财报数据
用百度搜索人工智能在教育领域的最新应用
```

### 常用命令速查

| 命令 | 功能说明 |
|------|----------|
| `/help` | 显示完整帮助文档 |
| `/exit` | 退出程序 |
| `/model` | 查看当前模型配置 |
| `/model list` | 列出所有可用模型 |
| `/model set NAME` | 切换到指定模型 |
| `/api_key` | 查看 API Key 状态 |
| `/api_key set KEY` | 设置 API Key |
| `/allow list` | 查看文件访问白名单 |
| `/allow add PATH` | 添加白名单路径 |
| `/tool list` | 查看所有可用的 MCP 工具 |
| `/web status` | 查看百度搜索配置 |
| `/web set KEY` | 设置百度搜索 Token |

---

## 🌟 典型应用场景

### 👥 普通用户：资料搜集与整理

**场景**：需要了解某个领域的最新动态

```text
请搜索最近一个月关于"人工智能医疗"的新闻，
用通俗语言总结 3 个重要突破，每个不超过 100 字。
```

**执行流程**：
1. 模型调用百度搜索 MCP 获取新闻
2. 筛选相关信息
3. 生成简洁易懂的中文总结

### 📚 学生/研究者：学习笔记管理

**场景**：创建并维护个人知识库

```text
在当前目录创建 study-notes 文件夹，
每天生成一个 markdown 文件（day1.md, day2.md...），
每个文件包含学习目标和反思区域。
```

### 👨‍💻 开发者：项目辅助开发

**场景**：代码审查与重构建议

```text
分析当前项目中所有超过 50 行的函数，
指出哪些可以拆分，并给出重构后的示例代码。
```

---

## 🔒 安全与隐私

### 数据安全承诺

- ✅ **本地存储**: 所有配置（包括 API Key）均保存在 `~/.momcp/config.toml`，仅本机可访问
- ✅ **明文存储**: 配置文件为 TOML 格式，便于查看和管理
- ✅ **无上传**: 不会将任何配置或对话内容上传至第三方服务器
- ✅ **白名单保护**: 文件操作严格限制在授权目录内

### 重置配置

如需清除所有配置：

```bash
rm -rf ~/.momcp
```

下次启动时会重新初始化。

---

## ❓ 常见问题

### Q: `momcp-tui` 命令不存在？

**A**: 确认已完成安装并激活了正确的 Conda 环境：

```bash
conda activate momcp
which momcp-tui  # macOS/Linux
where momcp-tui  # Windows
```

### Q: 提示缺少依赖包？

**A**: 手动安装所需依赖：

```bash
pip install textual httpx pydantic tomli mcp fastmcp
```

### Q: 模型报错"未配置 API Key"？

**A**: 
1. 使用 `/model` 确认当前模型系列
2. 使用 `/api_key set YOUR_KEY` 设置 Key
3. 或重新执行 `/model set MODEL_NAME` 按提示输入

### Q: 文件工具无法访问某目录？

**A**: 该目录不在白名单中，请使用：

```text
/allow add /path/to/directory
```

然后重启程序。

---

## 🛠️ 技术栈

- **TUI 框架**: [Textual](https://github.com/textualize/textual)
- **HTTP 客户端**: [HTTPX](https://www.python-httpx.org/)
- **数据验证**: [Pydantic](https://docs.pydantic.dev/)
- **MCP 协议**: [Model Context Protocol](https://modelcontextprotocol.io/)
- **本地服务**: [FastMCP](https://github.com/jlowin/fastmcp)

---

## 📄 开源协议

本项目采用 [MIT License](LICENSE)，您可以自由使用、修改和分发。

---

## 📬 联系方式

- **作者**: AndyJin
- **邮箱**: 2358155969@qq.com

---

<div align="center">

Made with ❤️ by AndyJin

</div>
