Skip to content

Commit 76353b8

Browse files
tcpipuktcpipuk
authored
Improve documentation accessibility
1 parent 37a521b commit 76353b8

File tree

4 files changed

+223
-181
lines changed

4 files changed

+223
-181
lines changed

‎README.md

+43-39
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,56 @@
11
# MCP Server
22

3-
This server offers tools that AI assistants can interact with safely to operate external tools and
4-
services using the Model Context Protocol (MCP). It pre-processes data to save tokens and make it
5-
easier for LLMs to understand, and provides informative errors when things go wrong.
3+
A server that lets AI assistants like Claude safely use external tools - like running Python code or
4+
accessing websites. It processes data to make it easier for AI to understand, and provides helpful
5+
error messages when things go wrong, so bots are more empowered to solve their own problems.
66

77
1. [🛠️ What tools does this server offer?](#️-what-tools-does-this-server-offer)
88
2. [🏎️ How can I run it?](#️-how-can-i-run-it)
9-
1. [🐋 Docker Compose](#-docker-compose)
10-
2. [💻 Local Development](#-local-development)
11-
3. [🔌 Which connection method should I use?](#-which-connection-method-should-i-use)
12-
4. [📚 Where can I read more about MCP?](#-where-can-i-read-more-about-mcp)
9+
1. [🐋 Using Docker (recommended)](#-using-docker-recommended)
10+
2. [💻 Running locally](#-running-locally)
11+
3. [🔌 How to connect](#-how-to-connect)
12+
4. [📚 Learn more about MCP](#-learn-more-about-mcp)
1313
5. [📄 License](#-license)
1414

1515
## 🛠️ What tools does this server offer?
1616

17-
The server provides tools for web content retrieval and code execution:
17+
Once running, your AI assistant will be able to:
1818

19-
| Tool | Description |
19+
| Tool | What it can do |
2020
|------|-------------|
21-
| [python](docs/python.md)| Executes or lints Python code in a resource-limited sandbox. Includes useful packages like numpy and pandas, with options to either run the code or check it with Ruff. |
22-
| [web](docs/web.md) | Accesses and processes content from a given URL. Depending on the mode ('markdown', 'raw', or 'links'), it can clean and format page content into markdown, return the raw unprocessed data, or extract internal links with their anchor text to facilitate further navigation. |
21+
| [Python](docs/python.md)| Run Python code safely in a sandbox. Includes popular packages like numpy and pandas for data analysis, and can either run code or check it for errors. |
22+
| [Web](docs/web.md) | Access websites and process their content. Can convert pages to markdown for easy reading, get the raw content, or extract links to help navigate through documentation. |
2323

2424
## 🏎️ How can I run it?
2525

26-
### 🐋 Docker Compose
26+
### 🐋 Using Docker (recommended)
27+
28+
1. [Install Docker](https://docs.docker.com/engine/install/) if you haven't already
29+
2. Create a file called `docker-compose.yml` with:
30+
31+
```yaml:docker-compose.yml
32+
services:
33+
mcp-server:
34+
environment:
35+
- SSE_HOST=0.0.0.0
36+
- SSE_PORT=8080
37+
- USER_AGENT=CustomAgent/1.0
38+
image: ghcr.io/tcpipuk/mcp-server:latest
39+
restart: unless-stopped
40+
stop_grace_period: 1s
41+
```
2742

28-
[Install Docker](https://docs.docker.com/engine/install/) if you haven't already, then put this in
29-
a `docker-compose.yml` and run `docker compose up` to start it:
43+
3. Run `docker compose up` to start the server
3044

31-
```yaml:docker-compose.yml
32-
services:
33-
mcp-server:
34-
environment:
35-
- SSE_HOST=0.0.0.0
36-
- SSE_PORT=8080
37-
- USER_AGENT=CustomAgent/1.0
38-
image: ghcr.io/tcpipuk/mcp-server:latest
39-
restart: unless-stopped
40-
stop_grace_period: 1s
41-
```
45+
> **Note**: The server will automatically use network mode (SSE) when you set `SSE_HOST` and
46+
> `SSE_PORT`. This is what you want for using it with LibreChat.
47+
48+
Most people use this with either:
4249

43-
> **Note**: If `SSE_HOST` and/or `SSE_PORT` environment variables are not set, the server will
44-
> automatically use `stdio` mode and listen on standard input/output.
50+
- [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) - connects directly to your computer
51+
- [LibreChat](https://www.librechat.ai/docs/local) - connects over the network
4552

46-
Normally you'd run this alongside [Claude Desktop](https://modelcontextprotocol.io/quickstart/user)
47-
(using stdio mode) or using [LibreChat](https://www.librechat.ai/docs/local) (using SSE mode), just
48-
putting something like this in your `librechat.yaml` to tell it how to talk to this MCP server:
53+
For LibreChat, add this to your `librechat.yaml` to connect:
4954

5055
```yaml:librechat.yaml
5156
mcpServers:
@@ -55,7 +60,7 @@ mcpServers:
5560
url: http://mcp-server:8080/sse
5661
```
5762

58-
### 💻 Local Development
63+
### 💻 Running locally
5964

6065
1. Install `uv` (requires Python 3.13+):
6166

@@ -100,17 +105,16 @@ Available arguments:
100105
> environment variables are not set) the server will automatically assume `stdio` mode and
101106
> listen on standard I/O.
102107
103-
## 🔌 Which connection method should I use?
108+
## 🔌 How to connect
104109

105-
You can run it using Docker, connect through standard input/output on the local machine, or use SSE
106-
over a network, which means it works directly with LibreChat and other MCP-compatible chat systems.
110+
You can connect to the server in two ways:
107111

108-
| Method | Best for | Notes |
109-
|--------|----------|--------|
110-
| Standard I/O (stdio) | Local development and testing | Direct process communication. Not recommended for Docker as it requires sharing the Docker socket. |
111-
| Server-Sent Events (SSE) | Production deployment | Runs as a network service. Recommended for Docker and cloud environments. |
112+
| Method | What it means | When to use it |
113+
|--------|---------------|----------------|
114+
| Network connection (SSE) | The server runs as a service that other apps can connect to | Best for most users - especially with LibreChat |
115+
| Direct connection (stdio) | The server runs directly on your computer | Useful for testing or development |
112116

113-
## 📚 Where can I read more about MCP?
117+
## 📚 Learn more about MCP
114118

115119
Here are a few resources to get you started:
116120

‎docs/images/web-usage.png

88.1 KB
Loading

‎docs/python.md

+94-64
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,88 @@
11
# Python Tool
22

3-
1. [Tool Schema](#tool-schema)
4-
2. [Execution Mode](#execution-mode)
5-
1. [Resource Limits](#resource-limits)
6-
2. [Available Packages](#available-packages)
7-
3. [Linting Mode](#linting-mode)
8-
4. [Error Handling](#error-handling)
9-
10-
The `python` tool provides code execution and linting capabilities to LLMs over MCP:
3+
1. [What can it do?](#what-can-it-do)
4+
2. [Available Packages](#available-packages)
5+
3. [Running Code](#running-code)
6+
4. [Safety and Limits](#safety-and-limits)
7+
5. [Error Handling](#error-handling)
8+
6. [Technical Details](#technical-details)
9+
1. [Sandbox Environment](#sandbox-environment)
10+
2. [Process Management](#process-management)
11+
3. [Code Quality Tools](#code-quality-tools)
12+
4. [Resource Management](#resource-management)
13+
14+
A tool that lets AI assistants run Python code safely. It includes popular data science packages
15+
and can either run code or check it for errors:
1116

1217
![Screenshot of GPT asked to perform a complex calculation then estimating π using Monte Carlo simulation](./images/python-usage.png)
1318

14-
It uses a dedicated virtual environment with pre-installed packages, running in a sandboxed
15-
environment with resource limits to ensure safe execution.
19+
## What can it do?
20+
21+
When you ask the AI to use Python, it can:
1622

17-
## Tool Schema
23+
- Run calculations and process data
24+
- Create visualisations and charts
25+
- Access the internet to fetch data
26+
- Check code for errors before running it
1827

19-
The description of the tool provided to the LLM explains why it should use the tool:
28+
The tool can either run your code directly or lint it first to catch potential issues. Linting is
29+
particularly useful when debugging or when you want to ensure code quality before running.
2030

21-
> Execute or lint Python code in a resource-limited sandbox. It has internet access, with aiodns,
22-
> aiohttp, bs4, numpy, pandas, and requests installed, so you can now test and solve a number of
23-
> problems without needing to directly calculate it yourself. Depending on your input parameters,
24-
> this tool either runs the code or lints with Ruff, so you can test code before running, or use
25-
> Ruff to help debugging if you get errors. The user can see the code you've submitted and the raw
26-
> returned response, but it's good etiquette to briefly summarise after using this tool what you
27-
> asked for and got back.
31+
## Available Packages
2832

29-
The arguments it is allowed to provide are:
33+
The tool comes with these useful packages pre-installed:
3034

31-
| Argument | Type | Required | Default | Description |
32-
|----------|------|----------|---------|-------------|
33-
| code | string | Yes | - | Python code to use |
34-
| timeout | integer | No | 10 | Timeout in seconds for execution (ignored when linting) |
35-
| lint | boolean | No | false | Lint the code using Ruff instead of executing it |
35+
| Package | What it's for |
36+
|---------|--------------|
37+
| `numpy`, `pandas` | Working with data - especially tables and calculations |
38+
| `requests`, `aiohttp` | Fetching data from the internet |
39+
| `bs4` (BeautifulSoup) | Processing web pages |
40+
| `ruff` | Checking code for errors |
3641

37-
## Execution Mode
42+
All packages run in a dedicated virtual environment to ensure consistency and security.
3843

39-
When `lint` is false, the tool executes the provided Python code in a sandboxed environment.
40-
The code runs in a dedicated virtual environment with pre-installed packages, isolated from the
41-
main application.
44+
## Running Code
4245

43-
### Resource Limits
46+
The AI can run Python code by providing:
4447

45-
The sandbox enforces the following limits:
48+
- The code to run (required)
49+
- How long to let it run for (optional, defaults to 10 seconds)
50+
- Whether to check the code for errors instead of running it (optional)
4651

47-
- Memory: 2GB maximum
48-
- CPU Time: 600 seconds (10 minutes)
49-
- Process Creation: Limited to prevent fork bombs
50-
- File Size: 50MB maximum output
51-
- Core Dumps: Disabled
52+
The code runs in a temporary directory that's cleaned up afterwards, and only has access to a
53+
limited set of environment variables (`LANG`, `TZ`, `PYTHONPATH`, and a few others) for security.
5254

53-
### Available Packages
55+
## Safety and Limits
5456

55-
The sandbox provides these pre-installed packages:
57+
To keep things safe and fast, the tool enforces strict resource limits:
5658

57-
- `aiodns`, `aiohttp` - Async network operations
58-
- `bs4` - HTML parsing
59-
- `numpy`, `pandas` - Data processing
60-
- `requests` - HTTP client
61-
- `ruff` - Python linter
59+
- Memory usage: Up to 2GB (via `RLIMIT_AS`)
60+
- CPU time: Up to 10 minutes (via `RLIMIT_CPU`)
61+
- Process creation: Limited to 50 processes (via `RLIMIT_NPROC`)
62+
- File operations: Up to 50MB (via `RLIMIT_FSIZE`)
63+
- Core dumps: Disabled (via `RLIMIT_CORE`)
6264

63-
## Linting Mode
65+
These limits are enforced using Linux resource limits (`setrlimit`) and can't be bypassed by the
66+
running code.
6467

65-
When `lint` is true:
68+
## Error Handling
6669

67-
- Uses Ruff to check code quality
68-
- Returns JSON-formatted output of any issues found
69-
- Reports "No issues found!" when code passes all checks
70-
- Ignores the `timeout` parameter (linting isn't time-limited)
70+
The tool captures both stdout and stderr, providing detailed error messages when things go wrong:
7171

72-
Example linting output:
72+
- Timeouts: `Execution terminated after {timeout} seconds`
73+
- Memory limits: `MemoryError: ...`
74+
- Import errors: `ImportError: No module named '...'`
75+
- Syntax errors: `SyntaxError: invalid syntax`
76+
- File system errors: `File system error: ...`
77+
- Process errors: `Process exited with code {code}`
78+
79+
When using linting mode, errors are returned in a structured JSON format:
7380

7481
```json
7582
[
7683
{
7784
"code": "E101",
78-
"message": "Indentation error: unexpected indent",
85+
"message": "Indentation contains mixed spaces and tabs",
7986
"location": {
8087
"line": 2,
8188
"column": 3
@@ -84,22 +91,45 @@ Example linting output:
8491
]
8592
```
8693

87-
## Error Handling
94+
## Technical Details
8895

89-
The tool captures both stdout and stderr, returning them in the response. Common errors include:
96+
The tool uses several layers of protection to ensure safe code execution:
9097

91-
```python
92-
# Timeout
93-
"Execution timed out"
98+
### Sandbox Environment
9499

95-
# Resource limits
96-
"MemoryError: ..."
100+
- Runs in an isolated temporary directory
101+
- Uses a dedicated virtual environment
102+
- Cleans up all temporary files after execution
103+
- Restricts environment variables to a safe allowlist
97104

98-
# Import errors
99-
"ImportError: No module named '...'"
105+
### Process Management
100106

101-
# Syntax errors
102-
"SyntaxError: invalid syntax"
103-
```
107+
- Uses `asyncio` for non-blocking execution
108+
- Supports graceful timeout handling
109+
- Captures and formats both stdout and stderr
110+
- Returns structured error information
111+
112+
### Code Quality Tools
113+
114+
- Uses Ruff for linting with most rules enabled:
115+
- All standard Python style checks
116+
- Common error patterns
117+
- Code complexity issues
118+
- Type checking hints
119+
- Ignores specific rules that aren't relevant:
120+
- `COM812`: Missing trailing comma
121+
- `CPY`: Copyright notice
122+
- `D100`: Missing docstring at the top of the file
123+
- `D203`, `D213`: Docstring formatting
124+
- `FBT`: Boolean arguments in function definitions
125+
- `RUF029`: Async methods that don't use `await`
126+
127+
### Resource Management
128+
129+
- Uses Linux kernel resource limits
130+
- Prevents fork bombs and memory exhaustion
131+
- Handles cleanup even after crashes
132+
- Supports both synchronous and asynchronous execution
104133

105-
Errors are always included in the output, whether from linting or execution, to help diagnose issues.
134+
The tool is designed to be both secure and helpful - it provides detailed error messages and
135+
linting suggestions while ensuring that code can't harm the system or use excessive resources.

0 commit comments

Comments
 (0)