138 lines
3.7 KiB
Markdown
138 lines
3.7 KiB
Markdown
# MCP Summary Server
|
|
|
|
An MCP (Model Context Protocol) server for document summarization that keeps full text out of the chat context window.
|
|
|
|
## Features
|
|
|
|
- Automatically determines whether to summarize directly or use chunked summarization
|
|
- All processing happens server-side
|
|
- Returns only the summary to the client
|
|
- Configurable chunking parameters
|
|
- Bearer token authentication (optional)
|
|
|
|
## Setup
|
|
|
|
### Environment Variables
|
|
|
|
Copy `.env.example` to `.env` and configure:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| PORT | 8080 | HTTP server port |
|
|
| API_KEY | (empty) | Bearer token for authentication |
|
|
| OPENAPI_URL | http://localhost:8080/v1 | LLM API endpoint |
|
|
| OPENAPI_API_KEY | (empty) | LLM API key |
|
|
| MODEL_NAME | gpt-4o | LLM model to use |
|
|
| LLM_TIMEOUT | 120 | LLM call timeout in seconds |
|
|
| CHUNK_SIZE | 4000 | Characters per chunk |
|
|
| OVERLAP | 200 | Characters of overlap between chunks |
|
|
| TARGET_INTERMEDIATE_SUMMARY_LENGTH | 150 | Words per chunk summary |
|
|
| MAX_DIRECT_SUMMARY_LENGTH | 100 | Max final summary length |
|
|
| MAX_DIRECT_TEXT_LENGTH | 8000 | Max text length before chunking |
|
|
|
|
## Running
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
# Build
|
|
docker build -t mcp-summary .
|
|
|
|
# Run with environment file
|
|
docker run -p 8080:8080 --env-file .env mcp-summary
|
|
|
|
# Run with inline environment variables
|
|
docker run -p 8080:8080 \
|
|
-e OPENAPI_URL=http://localhost:8080/v1 \
|
|
-e OPENAPI_API_KEY=your-key \
|
|
-e MODEL_NAME=gpt-4o \
|
|
mcp-summary
|
|
```
|
|
|
|
### Python
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
python mcp_summary_server.py
|
|
```
|
|
|
|
## Connecting to OpenWebUI
|
|
|
|
### In OpenWebUI Admin Settings
|
|
|
|
1. Go to **Admin Settings → External Tools**
|
|
2. Click **+ (Add Server)**
|
|
3. Set **Type** to **MCP (Streamable HTTP)**
|
|
4. Enter your **Server URL**
|
|
5. Set **Authentication**:
|
|
- **None** if no API key is configured
|
|
- **Bearer** if API_KEY is set (provide the key)
|
|
6. Save
|
|
|
|
### Docker Networking
|
|
|
|
If running both OpenWebUI and MCP Summary in Docker:
|
|
|
|
```bash
|
|
# Use host.docker.internal to reach host machine
|
|
docker run -p 8080:8080 \
|
|
-e OPENAPI_URL=http://host.docker.internal:3000/v1 \
|
|
-e OPENAPI_API_KEY=your-key \
|
|
mcp-summary
|
|
```
|
|
|
|
If both containers are on the same Docker network, use the container name directly:
|
|
|
|
```bash
|
|
docker run --network mynetwork -p 8080:8080 \
|
|
-e OPENAPI_URL=http://openwebui-container:8080/v1 \
|
|
-e OPENAPI_API_KEY=your-key \
|
|
mcp-summary
|
|
```
|
|
|
|
## MCP Tool
|
|
|
|
### summarize_document
|
|
|
|
Summarizes a document, automatically handling chunking for long text.
|
|
|
|
**Parameters:**
|
|
- `text` (string, required): The document text to summarize
|
|
- `max_length` (integer, optional): Maximum summary length in words (default: 100)
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"summary": "The summarized text...",
|
|
"original_length": 12345,
|
|
"method": "direct", // or "chunked"
|
|
"chunks": 1 // number of chunks used
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Failed to connect to MCP server"
|
|
|
|
1. **Check authentication**: Ensure you haven't selected `Bearer` without a key. Switch to `None` if no token is needed.
|
|
2. **Check network connectivity**: Ensure OpenWebUI can reach the MCP server URL
|
|
3. **Check LLM connectivity**: Ensure the MCP server can reach the LLM at OPENAPI_URL
|
|
4. **Check timeouts**: Increase LLM_TIMEOUT if summarization takes too long
|
|
|
|
### Infinite loading screen
|
|
|
|
This may occur if you configured the server as OpenAPI instead of MCP. Fix by:
|
|
|
|
1. Opening Admin Settings → External Tools
|
|
2. Disabling/deleting the problematic connection
|
|
3. Re-adding with **Type** set to **MCP (Streamable HTTP)**
|
|
|
|
### Slow initialization
|
|
|
|
If the server takes longer than 10 seconds to initialize:
|
|
- Increase `MCP_INITIALIZE_TIMEOUT` in OpenWebUI (default: 10 seconds)
|