Skip to content

Feat/spdv 993 stamp size input #15

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

Open
AndreiMitrea wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Feat/spdv 993 stamp size input #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed6a00a
Feat/mcp november standard updates (#23)
AndreiMitrea Mar 10, 2026
b09c075
feat: Create, extend postage batch tools accept varied size inputs
AndreiMitrea Mar 11, 2026
520359f
fix: Updated zod schemas
AndreiMitrea Mar 11, 2026
c12acaf
chore: Code review changes
AndreiMitrea Mar 11, 2026
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
1 change: 1 addition & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ BEE_API_URL=http://localhost:1633/
BEE_FEED_PK=
AUTO_ASSIGN_STAMP=true
DEFERRED_UPLOAD_SIZE_THRESHOLD_MB=5
TASK_TTL_MS=1200000
7 changes: 7 additions & 0 deletions .prettierrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"semi": true,
"trailingComma": "es5",
"singleQuote": false,
"printWidth": 80,
"tabWidth": 2
}
92 changes: 21 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,27 +23,25 @@ This server implements the Model Context Protocol (MCP), a standard protocol for

## Configuration Options

| Option | Type | Required | Description |
| ----------------------------------- | --------------| --------------| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BEE_API_URL` | string | **optional** (unless using your own node) | The URL of the Bee API endpoint. If omitted, the default Swarm Gateway will be used: `https://api.gateway.ethswarm.org`. Example: `http://localhost:1633`.|
| `BEE_FEED_PK` | string | **optional** (cannot update feed without it) | The private key of the Swarm Feed to use. If not provided, Swarm Feed functionality will be disabled. |
| `AUTO_ASSIGN_STAMP` | boolean | **optional** | Whether to automatically assign a postage stamp if none is provided. Default value is: true. Set to false to disable automatic stamp assignment. |
| `DEFERRED_UPLOAD_SIZE_THRESHOLD_MB` | number | **optional** | Size threshold in megabytes for deferred uploads. Files larger than this size will be uploaded asynchronously. Default value is: 5 (MB). |


| Option | Type | Required | Description |
| ----------------------------------- | ------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BEE_API_URL` | string | **optional** (unless using your own node) | The URL of the Bee API endpoint. If omitted, the default Swarm Gateway will be used: `https://api.gateway.ethswarm.org`. Example: `http://localhost:1633`. |
| `BEE_FEED_PK` | string | **optional** (cannot update feed without it) | The private key of the Swarm Feed to use. If not provided, Swarm Feed functionality will be disabled. |
| `AUTO_ASSIGN_STAMP` | boolean | **optional** | Whether to automatically assign a postage stamp if none is provided. Default value is: true. Set to false to disable automatic stamp assignment. |
| `DEFERRED_UPLOAD_SIZE_THRESHOLD_MB` | number | **optional** | Size threshold in megabytes for deferred uploads. Files larger than this size will be uploaded asynchronously. Default value is: 5 (MB). |
| `TASK_TTL_MS` | number | **optional** | Time to live of a task in milliseconds. Default value is: 1200000 (20 minutes). If the task TTL specified by the MCP client is larger than this value, that one will be used. |

## MCP Tools

The server provides the following MCP tools:


### `create_postage_stamp`

Buy postage stamp batch based on size in megabytes and duration.

**Parameters:**

- `size`: The storage size in MB (Megabytes). These other size units convert like this to MB: 1 byte = 0.000001 MB, 1 KB = 0.001 MB, 1GB= 1000MB.
- `size`: Storage capacity, e.g. 1GB, 1MB, 1KB.
- `duration`: Duration for which the data should be stored. Time to live of the postage stamp batch, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.
- `label`: (Optional) Sets label for the postage stamp batch.

Expand All @@ -67,7 +65,6 @@ Get a specific postage stamp batch based on batch id.
Give me the details for batch 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.
```


### `list_postage_stamps`

List the available postage stamp batches.
Expand All @@ -85,24 +82,22 @@ List the available postage stamp batches.
List my stamps.
```


### `extend_postage_stamp`

Increase the duration (relative to current duration) or size (in megabytes) of a postage stamp batch.

**Parameters:**

- `postageBatchId`: The id of the postage stamp batch for which extend is performed.
- `size`: (Optional) The storage size in MB (Megabytes). These other size units convert like this to MB: 1 byte = 0.000001 MB, 1 KB = 0.001 MB, 1GB= 1000MB.
- `size`: (Optional) Storage capacity, e.g. 1GB, 1MB, 1KB.
- `duration`: (Optional) Duration for which the data should be stored. Time to live of the postage stamp batch, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.

**Sample prompt:**

```bash
Extend 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa to 5 days.
Extend 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa by 5 days.
```


### `upload_data`

Upload text data to Swarm.
Expand All @@ -119,7 +114,6 @@ Upload text data to Swarm.
Upload data to Swarm: Hello World!.
```


### `download_data`

Downloads immutable data from a Swarm content address hash.
Expand All @@ -134,15 +128,14 @@ Downloads immutable data from a Swarm content address hash.
Download data from Swarm: 76d133e2798d2b15db55b6c3de01303acd86e43998eab372e25c5a2115bf3f0b.
```


### `update_feed`

Update the feed of a given topic with new data.

**Parameters:**

- `data`: Arbitrary string to upload.
- `memoryTopic`: If provided, uploads the lastes data to a feed with this topic. It is the label of the memory that can be used later to retrieve the data instead of its content hash. If not a hex string, it will be hashed to create a feed topic.
- `memoryTopic`: If provided, uploads the latest data to a feed with this topic. It is the label of the memory that can be used later to retrieve the data instead of its content hash. If not a hex string, it will be hashed to create a feed topic.
- `postageBatchId`: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.

**Sample prompt:**
Expand All @@ -151,7 +144,6 @@ Update the feed of a given topic with new data.
Update the Swarm feed of Topic1 with: Message1 using postage batch id 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.
```


### `read_feed`

Retrieve the latest data from the feed of a given topic.
Expand All @@ -167,7 +159,6 @@ Retrieve the latest data from the feed of a given topic.
Read the Swarm feed of Topic1.
```


### `upload_file`

Upload a file to Swarm.
Expand All @@ -185,15 +176,14 @@ Upload a file to Swarm.
Upload to Swarm the file: uploads/file.txt.
```


### `upload_folder`

Upload a folder to Swarm.

**Parameters:**

- `folderPath`: Path to the folder to upload.
- `redundancyLevel`: (Optional) Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid.
- `folderPath`: Path to the folder to upload.
- `redundancyLevel`: (Optional) Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid.
- `postageBatchId`: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.

**Sample prompt:**
Expand All @@ -202,12 +192,10 @@ Upload a folder to Swarm.
Upload to Swarm folder: /home/conversational-agent-client/uploads.
```


### `download_files`

Download folder, files from a Swarm reference and save to file path or return file list of the reference.


**Parameters:**

- `reference`: Swarm reference hash.
Expand All @@ -219,7 +207,6 @@ Download folder, files from a Swarm reference and save to file path or return fi
Download from Swarm the file with reference ba35af06601ddf5ac3d71ee33da0db7537215a914fd6a5414b5597bb3d618bdb to folder downloads.
```


### `query_upload_progress`

Query upload progress for a specific upload session identified with the returned Tag ID.
Expand Down Expand Up @@ -254,14 +241,7 @@ npm ci

### Configuration

The server configuration is located in `src/config.ts`:

You can customize:

- **Bee API endpoint**: Set to any Swarm Bee node or gateway
- **Postage Batch ID**: Required for uploading data to Swarm (the default ID is a placeholder for testing)

Modify these values as needed for your environment.
You need to create a `.env` file with the content from `.env.example`. Update the environment variables with the desired values.

## Running the Server Locally

Expand Down Expand Up @@ -298,9 +278,9 @@ npm start
npm run start:stdio
```

### Web Server (HTTP + SSE)
### Web Server (HTTP)

This runs the server as a web service on port 3000, with endpoints for both HTTP and SSE.
This runs the server as a web service on port 3000, with endpoints for HTTP.

**Development (without building):**

Expand All @@ -323,7 +303,7 @@ npm run start:web

## Docker

This project includes a Dockerfile to run the Swarm MCP server as a containerized service, with both HTTP and SSE transports.
This project includes a Dockerfile to run the Swarm MCP server as a containerized service with HTTP transport.

- `Dockerfile`: Builds a single image for the server, which runs on port 3000.

Expand All @@ -337,7 +317,7 @@ docker build -t swarm-mcp .

### Running the Docker Container

To run the server, use the `docker run` command. The container exposes port `3000` for both HTTP and SSE.
To run the server, use the `docker run` command. The container exposes port `3000` for HTTP.

```bash
docker run --name swarm-mcp -p 3000:3000 swarm-mcp
Expand All @@ -351,6 +331,8 @@ To configure the server, pass environment variables to the container using the `
docker run -p 3000:3000 \
-e BEE_API_URL="http://localhost:1633" \
-e BEE_FEED_PK="your_private_key_here" \
-e AUTO_ASSIGN_STAMP="true" \
-e DEFERRED_UPLOAD_SIZE_THRESHOLD_MB="5" \
swarm-mcp
```

Expand All @@ -377,45 +359,13 @@ _Note:_ `text/event-stream` in the accept header is required for the HTTP server

A successful response will be a JSON object containing a list of the server's tools.

#### SSE Server

Interacting with the SSE server is a two-step process. First, you establish a connection to get a `sessionId`, and then you use that ID to send messages.

**Step 1: Open the SSE connection**

Run the following command in a terminal. It will connect to the server and wait for events. The server will send back a `sessionId` which you will need for the next step.

```bash
# In Terminal 1
curl -N -H "Accept:text/event-stream" http://localhost:3000/sse
```

The output will contain the session ID, for example:
`id: "<your-session-id>"`

**Step 2: Send a message**

In a second terminal, use the `sessionId` from Step 1 to send a request. Replace `<your-session-id>` with the actual ID.

```bash
# In Terminal 2
curl -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' \
"http://localhost:3000/message?sessionId=<your-session-id>"
```

The response will appear in Terminal 1.

## Using with MCP Clients

The server supports two connection methods:

### 1. Web Connection (Docker)

When running the server in Docker, it operates as a web service with both HTTP and SSE endpoints. To connect your MCP client, you must use one that supports connecting to a remote server via URL.

- **HTTP Server URL**: `http://localhost:3000/mcp`
- **SSE Server URL**: `http://localhost:3000/sse`
When running the server in Docker, it operates as a web service with HTTP endpoint. To connect your MCP client, you must use: `http://localhost:3000/mcp`.

In your client's settings, add a new remote/custom connector and provide the appropriate URL.

Expand Down
Loading