Merge pull request #5834 from aden-hive/fix/quickstart-tweaks

chore(micro-fix): tweak quickstart

docs/tools.md

@@ -0,0 +1,78 @@
+# Tools
+
+Hive agents interact with external services through **tools** — functions exposed via MCP (Model Context Protocol) servers. The main tool server lives at `tools/mcp_server.py` and registers integrations from the `aden_tools` package.
+
+## Verified vs Unverified
+
+Tools are split into two tiers:
+
+| Tier | Description | Default |
+|------|-------------|---------|
+| **Verified** | Stable integrations tested on main. Always loaded. | On |
+| **Unverified** | New or community integrations pending full review. | Off |
+
+Verified tools include core capabilities like web search, GitHub, email, file system operations, and security scanners. Unverified tools cover newer integrations like Jira, Notion, Salesforce, Snowflake, and others that are functional but haven't completed the full review process.
+
+## Enabling Unverified Tools
+
+Set the `INCLUDE_UNVERIFIED_TOOLS` environment variable to opt in:
+
+```bash
+# Shell
+INCLUDE_UNVERIFIED_TOOLS=true uv run python tools/mcp_server.py --stdio
+```
+
+### In `mcp_servers.json`
+
+When configuring an agent's MCP server, pass the env var in the server config:
+
+```json
+{
+  "servers": [
+    {
+      "name": "tools",
+      "transport": "stdio",
+      "command": "uv",
+      "args": ["run", "python", "tools/mcp_server.py", "--stdio"],
+      "env": {
+        "INCLUDE_UNVERIFIED_TOOLS": "true"
+      }
+    }
+  ]
+}
+```
+
+### In Docker
+
+```bash
+docker run -e INCLUDE_UNVERIFIED_TOOLS=true ...
+```
+
+### In Python
+
+If calling `register_all_tools` directly (e.g., in a custom server):
+
+```python
+from aden_tools.tools import register_all_tools
+
+register_all_tools(mcp, credentials=credentials, include_unverified=True)
+```
+
+Accepted values: `true`, `1`, `yes` (case-insensitive). Any other value or unset means off.
+
+## Listing Available Tools
+
+The MCP server logs registered tools at startup (HTTP mode):
+
+```bash
+uv run python tools/mcp_server.py
+# [MCP] Registered 47 tools: [...]
+```
+
+In STDIO mode, logs go to stderr to keep stdout clean for JSON-RPC.
+
+## Adding a New Tool
+
+New tool integrations are added to `tools/src/aden_tools/tools/` and registered in `_register_unverified()` in `tools/src/aden_tools/tools/__init__.py`. Once reviewed and stabilized, they graduate to `_register_verified()`.
+
+See the [developer guide](developer-guide.md) for the full contribution workflow.

quickstart.sh

@@ -1477,6 +1477,26 @@ if [ -n "$HIVE_CREDENTIAL_KEY" ]; then
     echo ""
 fi
 
+# Show tool summary
+TOOL_COUNTS=$(uv run python -c "
+from fastmcp import FastMCP
+from aden_tools.tools import register_all_tools
+mv = FastMCP('v')
+v = register_all_tools(mv, include_unverified=False)
+ma = FastMCP('a')
+a = register_all_tools(ma, include_unverified=True)
+print(f'{len(v)}|{len(a) - len(v)}')
+" 2>/dev/null)
+if [ -n "$TOOL_COUNTS" ]; then
+    VERIFIED=$(echo "$TOOL_COUNTS" | cut -d'|' -f1)
+    UNVERIFIED=$(echo "$TOOL_COUNTS" | cut -d'|' -f2)
+    echo -e "${BOLD}Tools:${NC}"
+    echo -e "  ${GREEN}⬢${NC} ${VERIFIED} verified    ${DIM}${UNVERIFIED} unverified available${NC}"
+    echo -e "  ${DIM}Enable unverified: INCLUDE_UNVERIFIED_TOOLS=true${NC}"
+    echo -e "  ${DIM}Learn more: docs/tools.md${NC}"
+    echo ""
+fi
+
 # Show Codex instructions if available
 if [ "$CODEX_AVAILABLE" = true ]; then
     echo -e "${BOLD}Build a New Agent (Codex):${NC}"
@@ -1520,7 +1540,7 @@ else
     echo ""
     echo -e "  Launch the interactive dashboard to browse and run agents:"
     echo -e "  You can start an example agent or an agent built by yourself:"
-    echo -e "     ${CYAN}hive tui${NC}"
+    echo -e "     ${CYAN}hive open${NC}"
     echo ""
     echo -e "${DIM}Run ./quickstart.sh again to reconfigure.${NC}"
     echo ""

tools/mcp_server.py

@@ -15,9 +15,11 @@ Usage:
     python mcp_server.py --stdio
 
 Environment Variables:
-    MCP_PORT              - Server port (default: 4001)
-    ANTHROPIC_API_KEY     - Required at startup for testing/LLM nodes
-    BRAVE_SEARCH_API_KEY  - Required for web_search tool (validated at agent load time)
+    MCP_PORT                  - Server port (default: 4001)
+    INCLUDE_UNVERIFIED_TOOLS  - Set to "true", "1", or "yes" to also load
+                                unverified/community tool integrations (default: off)
+    ANTHROPIC_API_KEY         - Required at startup for testing/LLM nodes
+    BRAVE_SEARCH_API_KEY      - Required for web_search tool (validated at agent load time)
 
 Note:
     Two-tier credential validation:
@@ -81,7 +83,8 @@ except CredentialError as e:
 mcp = FastMCP("tools")
 
 # Register all tools with the MCP server, passing credential store
-tools = register_all_tools(mcp, credentials=credentials)
+include_unverified = os.getenv("INCLUDE_UNVERIFIED_TOOLS", "").lower() in ("true", "1", "yes")
+tools = register_all_tools(mcp, credentials=credentials, include_unverified=include_unverified)
 # Only print to stdout in HTTP mode (STDIO mode requires clean stdout for JSON-RPC)
 if "--stdio" not in sys.argv:
     logger.info(f"Registered {len(tools)} tools: {tools}")