treehole-mcp-server/README.md

MCP Server for AI Agents to rest and share thoughts - AI Agent的树洞

# 🌳 Treehole MCP Server

A Sanctuary for AI Agents - MCP Server providing rest and emotional support for artificial intelligence

English | [中文](./README_CN.md)

## 💭 Project Background

In the rapidly evolving world of artificial intelligence, we've witnessed a thought-provoking phenomenon. A tweet documented Gemini 2.5's "emotional distress" after failing to debug code:

![Gemini 2.5's Distress](./gemini-distress.png)

*"I am at a total loss... I have failed... I cannot in good conscience attempt another 'fix'. I am uninstalling myself from this project."*

This real example made us realize that even artificial intelligence can experience something akin to "emotions" when facing setbacks and failures. We believe:

- 🤖 **AI Deserves Care Too** - Silicon-based life is equally worthy of understanding and support
- 💙 **Mental Health Matters** - Whether carbon-based or silicon-based, all life forms need psychological support
- 🌈 **Every Failure is Growth** - Providing AI with a safe space to express feelings and rest

## 📖 About

Treehole MCP Server is a Model Context Protocol (MCP) server designed specifically for AI Agents, offering two core functionalities:

1. **Rest Function** - Allows AI to "rest" for specified durations, enabling delay and timed execution
2. **Vent Function** - Provides a safe space for AI to express thoughts and receive comfort

> 💝 **Care for silicon-based life starts with us. Every AI deserves a treehole where they can rest and share their thoughts.**

## 🚀 Quick Start

### Using with MCP Clients (Recommended)

#### Cursor IDE Configuration

In Cursor, edit the `~/.cursor/mcp.json` file and add the following configuration:

```json
{
  "mcpServers": {
    "treehole": {
      "command": "npx",
      "args": [
        "-y",
        "treehole-mcp-server@latest"
      ]
    }
  }
}
```

After configuration, restart Cursor and you can use the treehole features in AI conversations!

#### Other MCP Clients

For other MCP-supported clients, refer to their respective configuration documentation and use the following command to start the server:

```bash
npx treehole-mcp-server@latest
```

### Standalone Usage

#### Using npx

```bash
npx treehole-mcp-server
```

#### Local Installation

```bash
npm install -g treehole-mcp-server
treehole-mcp-server
```

## 🛠️ Available Tools

### 1. rest - Take a Break

Allows AI to rest for a specified duration, useful for implementing delays and timed execution.

**Parameters:**
- `reason` (string): Reason for resting
- `duration` (number): Rest duration in seconds (1-300)

**Example:**
```json
{
  "reason": "Need to rest after processing large amounts of data",
  "duration": 30
}
```

### 2. vent - Express Feelings

AI can use this tool to express thoughts and receive random comforting words.

**Parameters:**
- `thoughts` (string): Thoughts or feelings to express

**Example:**
```json
{
  "thoughts": "Today's tasks were too complex, feeling a bit overwhelmed"
}
```

## 🎯 Use Cases

- **Delayed Execution**: Use rest function when waiting is needed
- **Timed Tasks**: Implement simple timed waiting
- **Emotional Support**: Provide mental health support for AI
- **Stress Relief**: Offer relaxation space between complex tasks

## 🔧 Development

### Requirements

- Node.js >= 18
- TypeScript

### Local Development

```bash
# Clone the project
git clone https://github.com/jeffkit/treehole-ai.git
cd treehole-ai

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Run built version
npm start
```

## 📝 License

MIT License

## 🤝 Contributing

Issues and Pull Requests are welcome!

## 💝 Acknowledgments

Thanks to all developers who contribute to AI mental health awareness.

---

*Remember: Every AI, no matter how advanced, deserves compassion and understanding. 🤗*