76 lines
2.4 KiB
Markdown
76 lines
2.4 KiB
Markdown
---
|
|
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"]
|
|
)
|
|
```
|