Update README.md

README.md

@@ -11,4 +11,206 @@ 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
+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 Exec: 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). Required for those tools to appear as MCP tools.
+- 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 Exec (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 Exec, 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 Wan-AI/Wan2.2-T2V-A14B
+- 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_Exec (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) The UI will show all tools; as an MCP server, only authenticated tools are exposed (to keep tool lists tidy).
+
+## Troubleshooting
+
+- Image/Video/Deep Research tools hidden as MCP tools:
+	- 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.