README.md

---
title: Nymbo Tools MCP
emoji: ⚙️
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 6.0.2
app_file: app.py
pinned: true
license: apache-2.0
short_description: All-in-one hub of general purpose tools useful for any agent
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## Nymbo-Tools MCP Server

All-in-one hub of general-purpose tools useful for any agent. Run it as a Gradio web app, or connect to it remotely as a Model Context Protocol (MCP) server to call its tools programmatically.

Live Space: https://huggingface.co/spaces/Nymbo/Tools

### What’s inside

- Web Fetch: Turn any webpage into clean Markdown with optional link-only scraping, CSS selector stripping, length limits, and pagination via cursor offset.
- Web Search: DuckDuckGo-backed search across text, news, images, videos, and books with readable, paginated output.
- Code Interpreter: Execute small Python snippets and capture stdout.
- Memory Manager: Lightweight JSON-based memory store with save/list/search/delete and tag filters.
- Generate Speech: Kokoro‑82M TTS with 54 voices and adjustable speed (CPU or CUDA if available).
- Generate Image: Text-to-image via Hugging Face serverless inference (choose model, steps, CFG, size, seed).
- Generate Video: Text-to-video via Hugging Face serverless inference (model, steps, guidance, size, fps, duration, seed).
- Deep Research: Multi-query web research pipeline (DDG search + parallel fetch + LLM report synthesis) with downloadable report.
- File System: Safe, sandboxed filesystem operations under a tool root.
- Shell Command: Run shell commands inside the same safe root as File System.

## Quick start

Run the following commands in sequence to run the server locally:

```shell
git clone https://huggingface.co/spaces/Nymbo/Tools
cd Tools
python -m venv env
source env/bin/activate
pip install -r requirements.txt
python app.py
```

Defaults:
- The Gradio UI typically serves on http://127.0.0.1:7860
- The MCP endpoint is available at http://127.0.0.1:7860/gradio_api/mcp/

## Using it as an MCP server

Remote MCP (hosted):
- Base URL: https://mcp.nymbo.net/gradio_api/mcp/
- SSE endpoint (for clients that need it): https://mcp.nymbo.net/gradio_api/mcp/sse

Local MCP (when you run app.py):
- Base URL: http://127.0.0.1:7860/gradio_api/mcp/
- SSE endpoint: http://127.0.0.1:7860/gradio_api/mcp/sse

Example client config (JSON):

```json
{
	"mcpServers": {
		"nymbo-tools": {
			"url": "https://mcp.nymbo.net/gradio_api/mcp/"
		}
	}
}
```

## Environment variables (optional but recommended)

- HF_READ_TOKEN: Enables Image Generation, Video Generation, and Deep Research (Hugging Face serverless inference). These tools stay visible to MCP clients but calls require a valid token to succeed.
- HF_TOKEN: Alternative token fallback used by some providers (also enables Deep Research/Video).
- NYMBO_TOOLS_ROOT: Overrides the File System/Shell working root. Defaults to Nymbo-Tools/Filesystem.
- UNSAFE_ALLOW_ABS_PATHS=1: Allow absolute paths in File System and Shell Command (off by default for safety).

Notes:
- Without a HF API key, you can still use Web Fetch, Web Search, Code Interpreter, Memory Manager, File System, Shell Command, and Generate Speech.
- Generate Speech requires the kokoro package and its dependencies; it works on CPU and uses CUDA if available. Doesn't require an API key because it's computed on the server itself.

## Persistence and privacy

- Memory Manager stores entries in `memories.json` at the Nymbo-Tools folder root when running locally.
- File System defaults to the `Filesystem/` directory under Nymbo-Tools.
- In the public demo Space, storage is ephemeral and visible to anyone using the Space; avoid personal or sensitive data.

## Tool reference (signatures and behavior)

Below are the MCP tool parameters summarized by inputs, outputs, and notable behaviors.

### Web_Fetch (Webpages, converted to Markdown)
Inputs:
- url (str): Absolute URL to fetch (must return HTML).
- max_chars (int, default 3000): 0 = full page; otherwise truncates with a next_cursor notice.
- strip_selectors (str): Comma-separated CSS selectors to remove (e.g., .header, .footer, nav).
- url_scraper (bool): If true, return only a list of links from the page.
- offset (int): Character offset for pagination; pass the previous next_cursor to continue.

Output: Markdown string. If truncated, includes a next_cursor to continue.

### Web_Search (DuckDuckGo backend)
Inputs:
- query (str): DuckDuckGo query (supports site:, quotes, OR).
- max_results (int 1–20, default 5)
- page (int, default 1) or offset (int) for precise continuation
- search_type (str): "text" | "news" | "images" | "videos" | "books"

Output: Readable text with pagination hints and next_offset.

### Code_Interpreter (Python)
Inputs:
- code (str): Python source; stdout is captured.

Output: Captured stdout or the exception text.

### Memory_Manager (Simple JSON store)
Inputs:
- action: "save" | "list" | "search" | "delete"
- text (save only), tags (save only)
- query (search only): supports tag:name terms and AND/OR
- limit (list/search): default 20
- memory_id (delete): full UUID or unique prefix
- include_tags (bool): include tags when listing/searching

Output: Confirmation string, listing, search matches, or structured error text.

### Generate_Speech (Kokoro-82M)
Inputs:
- text (str)
- speed (float 0.5–2.0, default 1.25)
- voice (str): One of 54 voices (e.g., af_heart, am_liam, bf_alice, zf_xiaoyi…)

Output: (sample_rate:int, waveform:np.ndarray) – rendered as downloadable WAV in the UI.

### Generate_Image (HF inference)
Requires: HF_READ_TOKEN

Inputs:
- prompt (str)
- model_id (str): e.g., black-forest-labs/FLUX.1-Krea-dev
- negative_prompt (str)
- steps (1–100), cfg_scale (1–20), sampler (UI label), seed (-1=random), width/height

Output: PIL.Image. In UI, displayed and downloadable. Errors guide you to provide a token or fix model id.

### Generate_Video (HF inference)
Requires: HF_READ_TOKEN or HF_TOKEN

Inputs:
- prompt (str)
- model_id (str): default akhaliq/sora-2
- negative_prompt (str)
- steps (1–100), cfg_scale, seed, width/height, fps, duration (s)

Output: Temporary MP4 file path; UI shows a playable/downloadable video.

### Deep_Research (HF inference)
Requires: HF_READ_TOKEN or HF_TOKEN

Inputs:
- summary (str): One or more sentences describing the research task.
- query1..query5 (str) with max1..max5 (1–50). Total requested results across queries are capped at 50.

Behavior:
- Parallel DDG searches → fetch pages in budget → filter candidate sources with an LLM → synthesize a long, well-structured Markdown report and list of sources.

Output: (report_md, fetched_links_text, report_file_path)

### File_System (safe root)
Root:
- Defaults to `Nymbo-Tools/Filesystem` (or NYMBO_TOOLS_ROOT). Absolute paths disabled unless UNSAFE_ALLOW_ABS_PATHS=1.

Actions:
- list, read, write, append, mkdir, move, copy, delete, info, help

Key fields:
- path, content (write/append), dest_path (move/copy), recursive, show_hidden, max_entries, offset, max_chars, create_dirs, overwrite

Output:
- Human-readable listings or JSON-like error strings with code/message/hint.

### Shell_Command (same safe root)
Inputs:
- command (str): Single-string shell command (pipelines supported by the host shell).
- workdir (str): Relative to the root.
- timeout (s)

Output:
- Combined header + STDOUT/STDERR. Absolute paths disabled by default. Shell is detected automatically (PowerShell on Windows when available; bash/sh on POSIX).

## Running on Hugging Face Spaces

1) Duplicate the Space at https://huggingface.co/spaces/Nymbo/Tools.
2) In Space Settings → Secrets, add HF_READ_TOKEN (and/or HF_TOKEN) for model access.
3) Both the UI and MCP clients will list every tool. Image/Video/Deep Research still need a valid token when invoked.

## Troubleshooting

- Image/Video/Deep Research calls fail immediately:
	- Provide HF_READ_TOKEN (and optionally HF_TOKEN). Restart the app/Space.
- 401/403 when calling generation tools:
	- Token missing/insufficient permissions. Ensure your token can read the chosen model.
- Kokoro not found:
	- Install kokoro>=0.9.4. CPU works; CUDA used if available. Torch may be skipped on Apple Silicon by design.
- Windows PowerShell activation policy blocks venv activation:
	- Run PowerShell as Admin and set a suitable execution policy for the current user (e.g., RemoteSigned), or manually run `python app.py` after installing dependencies.
- File System or Shell path errors:
	- Paths are relative to the tool root. Set NYMBO_TOOLS_ROOT to customize. Set UNSAFE_ALLOW_ABS_PATHS=1 only if you fully trust the environment.

## License

Apache-2.0 (see Space metadata). If you duplicate the Space or use these tools, ensure your usage complies with the licenses and terms of the underlying models and providers.