Initial commit

.opencode/skills/mcp-forge-conventions/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mcp-forge-conventions
+description: How to call MCP tools from within mcp-forge execute_python scripts, including tool naming and injection syntax
+---
+
+# mcp-forge Conventions
+
+## Tool naming
+
+mcp-forge injects tools using their **bare function name**, not the namespaced name visible to the agent.
+
+| Agent-side name | mcp-forge `mcp_tools` value | In-script call |
+|---|---|---|
+| `searxng_search` | `"search"` | `search(...)` |
+| `searxng_fetch` | `"fetch"` | `fetch(...)` |
+| `rag-mcp_browse_documents` | `"browse_documents"` | `browse_documents(...)` |
+| `rag-mcp_search_records` | `"search_records"` | `search_records(...)` |
+
+The pattern: strip any server prefix (e.g. `searxng_`, `rag-mcp_`) and use only the function name.
+
+## Injection syntax
+
+Pass a JSON array of bare tool names to `mcp_tools`:
+
+```python
+mcp-forge_execute_python(
+    code='results = search(query="foo"); print(results)',
+    mcp_tools=["search", "fetch"]
+)
+```
+
+## Listing all available tools
+
+Use the agent-side `mcp-forge_list_injectable_tools` tool to get the full catalogue before writing scripts:
+
+```
+mcp-forge_list_injectable_tools(include_schemas=false)
+```
+
+Returns each tool's `tool_name` (injected name), `qualified_name` (`provider.tool`), and provider metadata (name, transport, url). Only tools whose providers are registered in mcp-forge's own config appear here — tools available to the OpenCode agent from other MCP servers (e.g. GitHub) are NOT automatically available inside mcp-forge.
+
+## Verifying a single tool name
+
+To confirm a specific tool name resolves before using it, pass it in `mcp_tools` and check the `available_tools` list in the response. Only successfully resolved tools appear there.
+
+```python
+mcp-forge_execute_python(
+    code='print("ok")',
+    mcp_tools=["search"]
+)
+# response includes: "available_tools": ["search"]
+# if the name is wrong, the whole call errors with "Tool '<name>' not found"
+```
+
+## Return values
+
+Injected tools return Python objects (lists, dicts). Handle both a direct value and a dict wrapper:
+
+```python
+data = search(query="foo")
+records = data.get("result", []) if isinstance(data, dict) else data
+```
+
+## Combining searxng + mcp-forge
+
+```python
+mcp-forge_execute_python(
+    code='''
+results = search(query="uv python", language="en")
+top = results[0]
+page = fetch(url=top["url"], max_chars=2000)
+print(page["content"])
+''',
+    mcp_tools=["search", "fetch"]
+)
+```