🚀 基于MCP协议的Flomo Web服务器和命令行工具

本项目提供了基于MCP（模型上下文协议）的Web服务器与命令行工具，用于和Flomo API进行交互。其目的在于方便地将笔记添加到Flomo中，并且支持在不同环境下使用。

🚀 快速开始

本项目提供了便捷的方式与Flomo API交互，以下是使用前的快速指引。

✨ 主要特性

• 提供命令行工具和Web服务器两种使用方式，满足不同场景需求。
• 方便快捷地将笔记添加到Flomo中。

📦 安装指南

从PyPI安装（推荐）

# 安装基本包
pip install mcp-server-flomo

# 安装开发依赖（可选）
pip install mcp-server-flomo[dev]

从源码安装

git clone https://github.com/yourusername/mcp-server-flomo-python.git
cd mcp-server-flomo-python
pip install -r requirements.txt

📚 详细文档

项目结构

.
├── flomo_cli.py         # 命令行工具的主入口脚本
├── flomo_server.py      # Web服务器的主入口脚本
├── src                  # 源代码目录
│   ├── cli              # 命令行工具模块
│   │   ├── __init__.py
│   │   ├── __main__.py  # CLI程序的主要实现
│   │   └── commands.py  # 定义具体的命令
│   ├── server           # Web服务器模块
│   │   ├── __init__.py
│   │   ├── __main__.py  # 服务器的主实现
│   │   └── app.py       # 基于Flask的应用实现
│   └── utils            # 工具函数模块
│       ├── __init__.py
│       ├── config.py    # 配置管理工具
│       └── flomo_client.py  # Flomo API客户端的实现
├── tests                # 测试用例目录
└── docs                 # 文档目录

配置指南

1. 在项目根目录下创建一个.env文件：

FLOMO_API_URL=https://flomoapp.com/iwh/你的ID/你的API密钥/

⚠️ 重要提示

FLOMO_API_URL是必需的配置，可以从Flomo官网的“设置 > API”页面获取。

💻 使用示例

命令行工具

安装完成后，可以直接使用flomo-cli命令：

# 测试连接状态
flomo-cli test

# 发送一条笔记到Flomo
flomo-cli send "今天是个好天气"

# 从文件中读取内容并发送到Flomo
flomo-cli file path/to/note.txt

Web服务器

使用flomo-server启动Web服务：

flomo-server run

默认情况下，Web服务器将在http://localhost:12345上运行，并提供以下接口：

• /test：测试连接状态。
• /send：发送一条笔记到Flomo。
• /file：从指定文件中读取内容并发送到Flomo。

🔧 技术细节

开发指南

安装依赖

要进行开发，首先安装所有必要的包和工具：

pip install -r requirements.txt
pip install black pytest mypy

运行测试

使用以下命令运行测试用例：

pytest tests/

代码格式化

在项目中使用black来保持一致的代码风格：

black .

类型检查

使用mypy进行静态类型检查：

mypy src/

故障排除

1. 无法连接Flomo API：
   • 确保FLOMO_API_URL配置正确。
   • 检查网络连接，确保可以访问外部服务。
2. 端口被占用：
   • 如果flomo-server run提示端口被占用，尝试使用不同的端口号：

     flomo-server run --port 12346
     

3. 权限问题：
   • 确保运行程序的用户有权限访问所需的文件和网络资源。

贡献指南

提交代码

1. 创建一个分支用于功能开发：

git checkout -b feature/新功能名称

2. 完成代码修改后，提交到该分支并推送到远程仓库：

git add .
git commit -m "添加新功能：描述"
git push origin feature/新功能名称

3. 提交Pull Request到main分支，并在团队内部进行代码审查。

问题报告

发现任何问题，请通过以下方式提交：

1. 在GitHub Issues中创建一个新的问题。
2. 提供详细的错误信息和复现步骤。

📄 许可证

本项目遵循MIT License协议，具体内容如下：

MIT License

版权 © [年份] [姓名或组织名称]

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.

通过以上文档，您可以轻松地安装、配置和使用这个项目。如果在使用过程中遇到任何问题，请随时参考本指南或联系开发团队寻求帮助。