README.md

metadata

title: Nymbo Tools MCP
emoji: ⚙️
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 5.43.1
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:

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):

{
    "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.