Skip to content

feat: add community. #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PttCodingMan merged 3 commits into from
Jul 9, 2025
Merged

feat: add community. #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b0e460a
feat: add community.
PttCodingMan Jul 9, 2025
a2518ae
feat: add community.
PttCodingMan Jul 9, 2025
1659a43
Merge branch 'feat/add-community' of https://github.com/PyPtt/ptt_mcp…
PttCodingMan Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 0 additions & 48 deletions .github/workflows/translate_readme.yml
View file
Open in desktop

This file was deleted.

6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<!-- readme: collaborators,contributors -start -->
Expand Down
222 changes: 122 additions & 100 deletions README_ENG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,78 +2,92 @@

<h1 align="center">PTT MCP Server</h1>

<p align="center">
The best MCP server for Ptt. Proudly built by the <a href="https://pyptt.cc/">PyPtt</a> developer.
<br />
<br />
<a href="https://pypi.org/project/ptt-mcp-server/">
<img src="https://img.shields.io/pypi/v/ptt-mcp-server.svg" alt="PyPI Version">
</a>
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
</a>
<a href="https://img.shields.io/pypi/dm/ptt-mcp-server">
<img src="https://img.shields.io/pypi/dm/ptt-mcp-server" alt="Downloads">
</a>
<a href="https://github.com/PyPtt/ptt_mcp_server/blob/main/LICENSE">
<img src="https://img.shields.io/badge/license-BSD_3--Clause-blue.svg" alt="License">
</a>
<p align="center">
The best MCP server for Ptt. Proudly built by the <a href="https://pyptt.cc/">PyPtt</a> developer.
<br />
<br />
<a href="https://pypi.org/project/ptt-mcp-server/">
<img src="https://img.shields.io/pypi/v/ptt-mcp-server.svg" alt="PyPI Version">
</a>
<a href="https://www.python.org/downloads/">
<img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
</a>
<a href="https://img.shields.io/pypi/dm/ptt-mcp-server">
<img src="https://img.shields.io/pypi/dm/ptt-mcp-server" alt="Downloads">
</a>
<a href="https://github.com/PyPtt/ptt_mcp_server/actions/workflows/code_quality.yml">
<img src="https://github.com/PyPtt/ptt_mcp_server/actions/workflows/code_quality.yml/badge.svg" alt="code_quality">
</a>
<a href="https://github.com/PyPtt/ptt_mcp_server/blob/main/LICENSE">
<img src="https://img.shields.io/badge/license-BSD_3--Clause-blue.svg" alt="License">
</a>
</p>

## 📖 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"]
Expand All @@ -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.

Expand All @@ -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
{
Expand Down Expand Up @@ -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**

<!-- readme: collaborators,contributors -start -->
<table>
Expand Down Expand Up @@ -220,11 +240,13 @@ Contributions of any kind are welcome! Whether it's reporting an issue or submit
</table>
<!-- readme: collaborators,contributors -end -->

## 🙏 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).