diff --git a/.github/workflows/translate_readme.yml b/.github/workflows/translate_readme.yml deleted file mode 100644 index e56bcc6..0000000 --- a/.github/workflows/translate_readme.yml +++ /dev/null @@ -1,48 +0,0 @@ -name: Translate README with Gemini - -on: - push: - branches-ignore: - - 'main' - paths: - - 'README.md' - workflow_dispatch: - -jobs: - translate: - runs-on: ubuntu-latest - permissions: - contents: write - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Read README.md content - id: read_file - uses: jellyfishsdk/read-file-action@v1 - with: - path: 'README.md' - - - name: Call Gemini API for Translation - id: call_gemini - uses: google-gemini/gemini-api-action@v1 - with: - api_key: ${{ secrets.GEMINI_API_KEY }} - prompt: "Please translate the following Markdown text from Traditional Chinese to English. It is for a GitHub project's README file. Preserve all original Markdown formatting, including code blocks, links, tables, and HTML tags. Do not add any extra commentary, introductions, or explanations outside of the translated text itself. Just return the pure, translated Markdown content. Here is the text:\n\n${{ steps.read_file.outputs.content }}" - - - name: Update README_ENG.md with translation - run: | - echo "${{ steps.call_gemini.outputs.response }}" > README_ENG.md - - - name: Commit and push if changed - run: | - git config --global user.name 'github-actions[bot]' - git config --global user.email 'github-actions[bot]@users.noreply.github.com' - git add README_ENG.md - if ! git diff --staged --quiet; then - git commit -m "docs: auto-translate README.md to English via Gemini" - git push - else - echo "No changes to commit." - fi \ No newline at end of file diff --git a/README.md b/README.md index 18b6ad0..e249eed 100644 --- a/README.md +++ b/README.md @@ -208,6 +208,12 @@ pip install ptt-mcp-server 4. Push 到您的分支 (`git push origin feature/AmazingFeature`)。 5. 開啟一個 Pull Request。 +## 💬 社群 (Community) + +歡迎加入我們的社群,與其他開發者交流! + +- [**Telegram**](https://t.me/PyPtt) + ## 👥 貢獻者 (Contributors) diff --git a/README_ENG.md b/README_ENG.md index 7967d14..accf2dc 100644 --- a/README_ENG.md +++ b/README_ENG.md @@ -2,78 +2,92 @@

PTT MCP Server

-

-The best MCP server for Ptt. Proudly built by the PyPtt developer. -
-
- -PyPI Version - - -Python 3.10+ - - -Downloads - - -License - +

+The best MCP server for Ptt. Proudly built by the PyPtt developer. +
+
+ +PyPI Version + + +Python 3.10+ + + +Downloads + + +code_quality + + +License +

-## 📖 Description -This project is a PTT MCP (Model Context Protocol) server based on the powerful [`PyPtt`](https://pyptt.cc/) library. It enables your MCP client to directly log into PTT, interact with the PTT Bulletin Board System through the MCP protocol, and perform automated operations. - -## 🚀 Quick Start - -1. **Install the package:** - ```bash - pip install ptt-mcp-server - ``` - -2. **Configure your MCP client:** - Add the following configuration to your MCP client's settings file and fill in your PTT credentials. - - ```json - { - "mcpServers": { - "PTT": { - "command": "ptt-mcp-server", - "env": { - "PTT_ID": "YOUR_PTT_ID", // Replace with your PTT ID - "PTT_PW": "YOUR_PTT_PW" // Replace with your PTT password - } - } - } - } - ``` +## **📖 Description** + +This project is a PTT MCP (Model Context Protocol) server based on the powerful [PyPtt](https://www.google.com/search?q=%5Bhttps://pyptt.cc/%5D(https://pyptt.cc/)) library. It enables your MCP client to genuinely log into PTT and perform actual interactions and automated operations with the PTT Bulletin Board System via the MCP protocol. + +## **🚀 Quick Start** + +1. **Install the package (using venv):** -3. **Launch and test:** - Your MCP client should now be able to automatically start the PTT MCP server. You can test the connection by trying a simple command, such as asking it to log into PTT. + ```bash + python3 -m venv venv + source venv/bin/activate + pip install ptt-mcp-server + ``` -## 💡 Usage Example + * When you use it the next time, you can just start from source venv/bin/activate 😊 +3. Configure your MCP client: + Add the following configuration to your MCP client's settings file and fill in your PTT account ID and password. + For example, if you are using gemini-cli, you can copy and paste this into the .gemini/settings.json file in your current project folder. + + ```json + { + "mcpServers": { + "PTT": { + "command": "ptt-mcp-server", + "env": { + "PTT_ID": "YOUR_PTT_ID", // Please replace with your own PTT ID + "PTT_PW": "YOUR_PTT_PW" // Please replace with your own PTT password + } + } + } + } + ``` + +4. Launch and Test: + Your MCP client should now be able to automatically start the PTT MCP server. You can try a simple command to test the connection, such as asking it to log in to PTT. + +## **💡 Usage Example** Once your MCP client (e.g., Gemini CLI) is configured, you can interact with PTT like this: -**You type:** -> Log me into PTT +**You input:** +``` +Help me log in to PTT +``` +**MCP Client Execution (Behind the scenes):** -**MCP Client Execution (Behind the Scenes):** -1. The Gemini CLI calls the `login` function via the MCP protocol. -2. `ptt-mcp-server` receives the command and uses the `PyPtt` library to perform the login. -3. `ptt-mcp-server` returns the login result (success or failure) to the Gemini CLI. +1. Gemini CLI calls the login function via the MCP protocol. +2. `ptt-mcp-server` receives the command and executes the login using the PyPtt library. +3. `ptt-mcp-server` returns the login success or failure result to Gemini CLI. **You will see:** -> Login successful +``` +Login successful +``` + +## **⚙️ How it Works** -## ⚙️ How it Works -This project acts as middleware. Your MCP client (e.g., Gemini CLI) connects to the locally running `ptt-mcp-server`. When the server receives a command, it uses the [`PyPtt`](https://pyptt.cc/) library to connect to PTT and execute the corresponding action, finally returning the result to your client. +This project acts as a middle layer. Your MCP client (e.g., Gemini CLI) connects to the ptt-mcp-server running locally. When the server receives a command, it connects to PTT through the [PyPtt](https://www.google.com/search?q=%5Bhttps://pyptt.cc/%5D(https://pyptt.cc/)) library, performs the corresponding action, and sends the result back to your client. ```mermaid graph LR A["MCP Client"] subgraph B ["PTT MCP Server"] - D["PyPtt Library"] + D["PyPtt"] end C["PTT.cc Website"] @@ -82,36 +96,36 @@ graph LR B <--> C ``` -## ✨ Features in Detail +## **✨ Features in Detail** -| Category | Operations | Status | -|:---------------------|:-------------------------------------------------|:-------| -| **Account Management** | Login, Logout | ✅ | -| **Post Management** | Get post list, Read post, Create new post, Delete post | ✅ | -| **Post Interaction** | Push, Boo, Arrow, Reply to post | ✅ | -| **Mail System** | Read mail, Send new mail, Delete mail | ✅ | -| **Financial System** | Check P Coin balance, Transfer P Coins | ✅ | -| **Information Query** | Query user info, Query board info, **Get post index range** | ✅ | +| Feature Category | Specific Operation | Support Status | +| :---- | :---- | :---- | +| **Account Management** | Login, Logout | ✅ | +| **Post Management** | Get post list, Read post content, Create new post, Delete post | ✅ | +| **Post Interaction** | Push, Shush, Give arrow, Reply to post | ✅ | +| **Mailbox System** | Read mail, Send new mail, Delete mail | ✅ | +| **Financial System** | Check P-coins, Transfer P-coins | ✅ | +| **Information Query** | Query user info, Query board info, **Get post index range** | ✅ | -## ⚠️ Important Suggestion & Disclaimer +## **⚠️ Important Suggestion & Disclaimer** -This project provides powerful PTT automation capabilities, but please note that all actions are based on your authorization, and you are fully responsible for the consequences of all operations. To use this tool safely and effectively, we strongly recommend following these best practices: +This project provides powerful PTT automation capabilities. However, please be aware that all operations are based on your authorization, and you are fully responsible for the consequences of all actions. To use this tool safely and effectively, we strongly recommend following these best practices: -**Best Practice: Read Before You Write, Confirm Before You Execute** +**Best Practice: Read before you write, confirm before you execute** -Before using any function that modifies PTT content (such as posting, replying, sending mail, pushing comments, etc.), be sure to first use read functions to gather and confirm information. +Before using any function that modifies PTT content (such as posting, replying, sending mail, pushing, etc.), always use the read functions first to gather and confirm information. -* **Example:** Instead of directly ordering to "delete violating posts," first "list all violating posts." After you have reviewed the list and confirmed its accuracy, then execute the deletion. +* **Example:** Instead of directly ordering "delete violating posts," first "list all violating posts." After you have reviewed the list and confirmed it is correct, then execute the deletion. -This simple process can significantly reduce the risk of operational errors (e.g., accidental deletion of posts, sending incorrect content). Although the PTT MCP Server will prompt you for final confirmation before execution, it cannot completely prevent the possibility of incorrect operations. **Please carefully check the content before submitting!** +This simple process can significantly reduce the risks associated with automation errors (e.g., accidental deletion of posts, sending incorrect content). Although PTT MCP Server prompts you for final confirmation before execution, it cannot completely prevent the possibility of misoperation. **Please double-check the content before sending!** -Please remember that the developers of this project are not responsible for any loss or liability caused by the use of this server. +Please remember that the developers of this project are not responsible for any loss or liability caused by using this server. -## 📋 Requirements +## **📋 Requirements** * Python 3.10 or newer. -## 🚀 Installation & Setup +## **🚀 Installation & Setup** Please follow the steps below to install and set up your MCP server. @@ -125,13 +139,13 @@ pip install ptt-mcp-server ### **Step 2: Configure the MCP Client** -Your MCP client needs to know how to start this server. Here are two ways to configure it. +Your MCP client needs to know how to start this server. Two configuration methods are provided below. -**Security Tip:** It is recommended to use environment variables for your PTT credentials to avoid writing sensitive information directly in configuration files. +**Security Tip**: It is recommended to use environment variables to set your PTT ID and password to avoid writing sensitive information directly in the configuration file. -#### **Method A: Standard Path (Recommended)** +#### **Method A: Standard Path Configuration (Recommended)** -After installation, the `ptt-mcp-server` command should be available in your shell. This is the simplest setup method. +After installation, ptt-mcp-server should already be in your system's Python environment. This is the simplest configuration method. ```json { @@ -164,31 +178,37 @@ If you use a Python virtual environment, or if the `command` cannot be executed **How to find the paths?** -* **command**: After activating your virtual environment, run `which python3`. -* **args**: After activating your virtual environment, run `which ptt-mcp-server`. +* **command**: After activating your virtual environment, run which python3. +* **args**: After activating your virtual environment, run which ptt-mcp-server. -## 🗺️ Roadmap +## **🗺️ Roadmap** -- [ ] Support for more PTT features (e.g., digest/best-of operations). -- [ ] Provide a Docker image to simplify the deployment process. -- [ ] Write more comprehensive documentation and examples. -- [ ] Optimize performance and connection stability. +* [ ] Support more PTT features (e.g., digest operations). +* [ ] Provide a Docker image to simplify deployment. +* [ ] Write more comprehensive documentation and examples. +* [ ] Optimize performance and connection stability. -Feel free to provide suggestions via [Issues](https://github.com/PyPtt/ptt_mcp_server/issues)! +Suggestions are welcome via [Issues](https://github.com/PyPtt/ptt_mcp_server/issues)! -## 🤝 Contributing +## **🤝 Contributing** -Contributions of any kind are welcome! Whether it's reporting an issue or submitting a pull request, we appreciate all input. Please feel free to share your ideas! +We warmly welcome any form of contribution! -- **Have questions or suggestions?** Open an issue on [GitHub Issues](https://github.com/PyPtt/ptt_mcp_server/issues). -- **Want to contribute code?** - 1. Fork the project. - 2. Create your feature branch (`git checkout -b feature/AmazingFeature`). - 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`). - 4. Push to the branch (`git push origin feature/AmazingFeature`). - 5. Open a Pull Request. +* **Have questions or suggestions?** Please open an issue on [GitHub Issues](https://github.com/PyPtt/ptt_mcp_server/issues). +* **Want to contribute code?** + 1. Fork this project. + 2. Create your feature branch (`git checkout -b feature/AmazingFeature`). + 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`). + 4. Push to your branch (`git push origin feature/AmazingFeatur`e). + 5. Open a Pull Request. -## 👥 Contributors +## **💬 Community** + +Feel free to join our community to chat with other developers! + +* [**Telegram**](https://t.me/PyPtt) + +## **👥 Contributors** @@ -220,11 +240,13 @@ Contributions of any kind are welcome! Whether it's reporting an issue or submit
-## 🙏 Acknowledgements +## **🙏 Acknowledgements** + +* [**PyPtt**](https://pyptt.cc/) - The core library that drives this project's interaction with PTT. +* [**fastmcp**](https://github.com/jlowin/fastmcp) - Provides a high-performance MCP server framework. -* [**PyPtt**](https://pyptt.cc/) - The core library that handles the interaction between this project and PTT. -* [**fastmcp**](https://github.com/jlowin/fastmcp) - Provides the high-performance MCP server framework. +For third-party libraries used in this project and their license terms, please refer to the [licenses](https://www.google.com/search?q=%5Bhttps://github.com/PyPtt/ptt_mcp_server/tree/main/licenses%5D(https://github.com/PyPtt/ptt_mcp_server/tree/main/licenses)) folder. -## 📄 License +## **📄 License** -This project is licensed under the [BSD 3-Clause License](https://github.com/PyPtt/ptt_mcp_server/blob/main/LICENSE). +This project is licensed under the [BSD 3-Clause License](https://github.com/PyPtt/ptt_mcp_server/blob/main/LICENSE). \ No newline at end of file