161 lines
3.8 KiB
Markdown
161 lines
3.8 KiB
Markdown
# 🧠 MCP Servers for the RIKO Project
|
||
|
||
This repository contains the **MCP (Model Context Protocol)** servers and tools that extend the **RIKO Project**, enabling Riko to communicate with:
|
||
|
||
* 🌐 External services — Discord, Gmail, Twitter, etc.
|
||
* 🧍 Local tools — lipsync, VRM animation, and Python code execution
|
||
|
||
Each MCP server is modular and self-contained, allowing Riko to connect and interact dynamically with multiple systems.
|
||
|
||
---
|
||
|
||
## ⚙️ Requirements
|
||
|
||
Before getting started, make sure you have:
|
||
|
||
* 🐍 **Python 3.10+**
|
||
* 🧰 A virtual environment (`python -m venv .venv`)
|
||
* 🚀 The **Riko Project** installed and configured
|
||
* 🌍 An **ngrok** account (for exposing local MCP servers)
|
||
* 🔑 API keys in a `.env` file, for example:
|
||
|
||
```bash
|
||
OPENAI_API_KEY=""
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Quickstart
|
||
|
||
### 1️⃣ Setup your environment
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
.venv\Scripts\activate # on Windows
|
||
source .venv/bin/activate # on Linux/Mac
|
||
|
||
pip install uv
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
### 2️⃣ Configure paths
|
||
|
||
Locate your Riko project directory (for example):
|
||
|
||
```
|
||
D:\PyProjects\waifu_project\riko_project_MCP
|
||
```
|
||
|
||
Then edit `riko_project_mcp_config.yaml` at the root of the riko project:
|
||
|
||
```yaml
|
||
riko_project_mcp_location: D:\PyProjects\waifu_project\riko_project_MCP
|
||
```
|
||
|
||
This tells all MCP tools where your main Riko MCP folder lives.
|
||
Each server will read this to locate `mcp_config.json`.
|
||
|
||
---
|
||
|
||
### 3️⃣ Directory layout example
|
||
|
||
```
|
||
riko_project_mcp/
|
||
│
|
||
├── riko_project_mcp_config.yaml
|
||
│
|
||
├── DiceCaller/
|
||
│ └── dice_server.py
|
||
│
|
||
├── DiscordBot/
|
||
│ └── discord_bridge.py
|
||
│
|
||
└── GmailSender/
|
||
└── gmail_server.py
|
||
```
|
||
|
||
Each folder (`DiceCaller`, `DiscordBot`, etc.) is a **server** —
|
||
the folder name automatically becomes the **server name** and **audience** for JWT authentication.
|
||
|
||
---
|
||
|
||
## 🧩 MCP Tool Types
|
||
|
||
Each tool inside a server must declare its type:
|
||
|
||
| Type | Description |
|
||
| ------------- | ---------------------------------------------------------------------------------- |
|
||
| **need_sync** | Tools that run in sync with Riko’s dialogue or playback |
|
||
| **can_async** | Tools that can run freely in the background |
|
||
| **long_task** | Tools that trigger longer background processes and return a “task started” message |
|
||
|
||
This classification helps Riko decide **when** and **how** to execute tools efficiently.
|
||
|
||
---
|
||
|
||
## 🧪 Running a Test Server
|
||
|
||
1. Launch the example Dice MCP server:
|
||
|
||
```bash
|
||
cd DiceCaller
|
||
python dice_server.py
|
||
```
|
||
|
||
2. Launch the manual MCP test:
|
||
|
||
```bash
|
||
python manual_mcp_call.py
|
||
```
|
||
|
||
If everything is connected correctly, you should see:
|
||
|
||
```
|
||
Result: {
|
||
'content': [{'type': 'text', 'text': '[2,3,5]'}],
|
||
'structuredContent': {'result': [2, 3, 5]},
|
||
'isError': False
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 Integrating with Riko
|
||
|
||
Once your MCP servers are running:
|
||
|
||
1. Launch your MCP server(s) first (e.g. `DiceCaller/dice_server.py`)
|
||
2. Run Riko’s startup script:
|
||
|
||
```bash
|
||
start_servers.bat
|
||
```
|
||
3. Then start Riko’s main system:
|
||
|
||
```bash
|
||
python main_chat_stream_tools.py
|
||
```
|
||
|
||
This will connect Riko to all active MCP servers and enable tool calls in real-time.
|
||
|
||
---
|
||
|
||
## 📜 Notes
|
||
|
||
* Each MCP server automatically creates and stores its credentials under:
|
||
|
||
```
|
||
~/riko_project_mcp/<server_name>/mcp_config.json
|
||
```
|
||
* Cross-platform compatible with **Windows**, **Linux**, and **WSL2**
|
||
* Uses **ngrok** for public tunneling (optional, configurable in YAML)
|
||
|
||
---
|
||
|
||
## 🪪 License
|
||
|
||
This project is currently **private** and not for redistribution.
|
||
It will be made public at a later date.
|
||
Please **do not share** this repository or any of its contents until then. |