> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Registry Bridge Module

> Bridge praisonaiagents.tools to MCP server registry with lazy loading

# MCP Registry Bridge Module

The Registry Bridge adapter connects the `praisonaiagents.tools` registry to the `praisonai.mcp_server` registry, enabling tools from PraisonAI Agents to be exposed via MCP without code duplication.

## Overview

**Key Features:**

* Lazy loading: Tools are only imported when first called
* Automatic hint inference from tool names
* Namespace prefixing to avoid collisions
* No eager imports or performance impact

## Code Usage

### Check Bridge Availability

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import is_bridge_available

if is_bridge_available():
    print("praisonaiagents.tools is available")
else:
    print("praisonaiagents not installed")
```

### Register Bridged Tools

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import register_praisonai_tools

# Register all tools from praisonaiagents
count = register_praisonai_tools()
print(f"Registered {count} tools")

# With custom namespace prefix
count = register_praisonai_tools(namespace_prefix="agents.")
```

### Unregister Bridged Tools

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import unregister_bridged_tools

# Remove all bridged tools
removed = unregister_bridged_tools()
print(f"Removed {removed} tools")
```

### Check Bridge Status

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import (
    is_bridge_enabled,
    get_bridged_tool_count,
    list_bridged_tools,
)

if is_bridge_enabled():
    print(f"Bridge active with {get_bridged_tool_count()} tools")
    for tool_name in list_bridged_tools():
        print(f"  - {tool_name}")
```

## Automatic Hint Inference

The bridge automatically infers tool annotation hints from tool names:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import _infer_tool_hints

# Read-only patterns
hints = _infer_tool_hints("memory.show")
print(hints["read_only_hint"])  # True
print(hints["destructive_hint"])  # False

# Destructive patterns (default)
hints = _infer_tool_hints("file.delete")
print(hints["destructive_hint"])  # True

# Idempotent patterns
hints = _infer_tool_hints("config.set")
print(hints["idempotent_hint"])  # True

# Closed-world patterns
hints = _infer_tool_hints("session.create")
print(hints["open_world_hint"])  # False
```

### Inference Rules

| Pattern                                                  | Hint               | Value   |
| -------------------------------------------------------- | ------------------ | ------- |
| show, list, get, read, search, find, query, info, status | `read_only_hint`   | `True`  |
| set, update, configure                                   | `idempotent_hint`  | `True`  |
| memory, session, config, local                           | `open_world_hint`  | `False` |
| (default)                                                | `destructive_hint` | `True`  |

## Lazy Handler Creation

Tools are loaded lazily - the module is only imported when the tool is first called:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import _create_lazy_handler

# Create a lazy handler
handler = _create_lazy_handler(
    module_path="praisonaiagents.tools.web",
    class_name="WebSearchTool",
    tool_name="web.search"
)

# Module is NOT imported yet
# ...

# First call imports the module
result = handler(query="test")  # Now the module is imported
```

## Category Extraction

Categories are extracted from tool names:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters.tools_bridge import _extract_category

category = _extract_category("praisonai.memory.show")
print(category)  # "memory"

category = _extract_category("web.search")
print(category)  # "web"

category = _extract_category("tool")
print(category)  # None (single-part name)
```

## Integration with MCP Server

### Automatic Registration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.adapters import register_all, register_praisonai_tools

# Register all built-in tools
register_all()

# Optionally add bridged tools
if is_bridge_available():
    register_praisonai_tools()
```

### Server with Bridge

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.server import MCPServer
from praisonai.mcp_server.adapters import register_all_tools
from praisonai.mcp_server.adapters.tools_bridge import (
    is_bridge_available,
    register_praisonai_tools,
)

# Create server
server = MCPServer(name="my-server")

# Register built-in tools
register_all_tools()

# Add bridged tools if available
if is_bridge_available():
    count = register_praisonai_tools()
    print(f"Added {count} tools from praisonaiagents")

# Start server
server.run()
```

## Collision Handling

### Skip on Collision (Default)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Tools with existing names are skipped
count = register_praisonai_tools(skip_on_collision=True)
```

### Error on Collision

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
try:
    count = register_praisonai_tools(skip_on_collision=False)
except ValueError as e:
    print(f"Collision detected: {e}")
```

## Performance Characteristics

| Operation                    | Performance               |
| ---------------------------- | ------------------------- |
| `is_bridge_available()`      | \~1ms (uses `find_spec`)  |
| `register_praisonai_tools()` | O(n) where n = tool count |
| Tool first call              | Module import time        |
| Tool subsequent calls        | Direct function call      |

## Best Practices

1. **Check availability** before registering bridged tools
2. **Use namespace prefix** to avoid collisions with built-in tools
3. **Register once** at server startup, not per-request
4. **Handle missing praisonaiagents** gracefully

## Example: Conditional Bridge

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.mcp_server.server import MCPServer
from praisonai.mcp_server.adapters import register_all_tools

server = MCPServer(name="my-server")
register_all_tools()

# Conditionally add agent tools
try:
    from praisonai.mcp_server.adapters.tools_bridge import (
        is_bridge_available,
        register_praisonai_tools,
    )
    
    if is_bridge_available():
        count = register_praisonai_tools(namespace_prefix="agents.")
        print(f"Bridge enabled: {count} agent tools available")
except ImportError:
    print("Bridge not available")

server.run()
```

## See Also

* [MCP Tool Annotations](/docs/mcp/mcp-tool-annotations) - Annotation hints
* [MCP Server](/docs/mcp/mcp-server) - Core MCP server
* [PraisonAI Agents Tools](/docs/tools/tools) - Agent tools documentation