Official LlamaIndex integration for Go Micro services. This package enables LlamaIndex agents to discover and call Go Micro microservices through the Model Context Protocol (MCP).

Features

Automatic Service Discovery - Discovers available services from MCP gateway
Dynamic Tool Generation - Converts service endpoints into LlamaIndex tools
Rich Descriptions - Uses service metadata for accurate tool descriptions
Authentication Support - Bearer token auth with scope-based permissions
RAG Integration - Combine service tools with LlamaIndex's RAG capabilities
Type-Safe - Fully typed with Python 3.8+ type hints

Installation

pip install go-micro-llamaindex

Quick Start

1. Start Your Go Micro Services

# Start MCP gateway
micro mcp serve --address :3000

2. Create LlamaIndex Agent

from go_micro_llamaindex import GoMicroToolkit
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

# Initialize toolkit from MCP gateway
toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")

# Create agent
llm = OpenAI(model="gpt-4")
agent = ReActAgent.from_tools(toolkit.get_tools(), llm=llm, verbose=True)

# Use the agent!
response = agent.chat("Create a user named Alice with email alice@example.com")
print(response)

Usage Examples

Basic Tool Discovery

from go_micro_llamaindex import GoMicroToolkit

# Connect to MCP gateway
toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")

# List available tools
for tool in toolkit.get_tools():
    print(f"Tool: {tool.metadata.name}")
    print(f"Description: {tool.metadata.description}")
    print()

Authentication

from go_micro_llamaindex import GoMicroToolkit

# Create toolkit with authentication
toolkit = GoMicroToolkit.from_gateway(
    gateway_url="http://localhost:3000",
    auth_token="your-bearer-token"
)

# Tools will automatically use the auth token
tools = toolkit.get_tools()

Filter Tools by Service

from go_micro_llamaindex import GoMicroToolkit

toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")

# Get only user service tools
user_tools = toolkit.get_tools(service_filter="users")

# Get tools matching a pattern
blog_tools = toolkit.get_tools(name_pattern="blog.*")

Custom Tool Selection

from go_micro_llamaindex import GoMicroToolkit

toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")

# Select specific tools
selected_tools = toolkit.get_tools(
    include=["users.Users.Get", "users.Users.Create"]
)

# Exclude certain tools
filtered_tools = toolkit.get_tools(
    exclude=["users.Users.Delete"]
)

RAG + Microservices

from go_micro_llamaindex import GoMicroToolkit
from llama_index.core import VectorStoreIndex, Document
from llama_index.core.agent import ReActAgent
from llama_index.core.tools import QueryEngineTool, ToolMetadata
from llama_index.llms.openai import OpenAI

toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")

# Combine service tools with a RAG query engine
index = VectorStoreIndex.from_documents([...])
rag_tool = QueryEngineTool(
    query_engine=index.as_query_engine(),
    metadata=ToolMetadata(name="docs", description="Search documentation"),
)

all_tools = [rag_tool] + toolkit.get_tools()
agent = ReActAgent.from_tools(all_tools, llm=OpenAI(model="gpt-4"))

Multi-Agent Workflows

from go_micro_llamaindex import GoMicroToolkit
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")
llm = OpenAI(model="gpt-4")

# Agent 1: User management
user_agent = ReActAgent.from_tools(
    toolkit.get_tools(service_filter="users"), llm=llm
)

# Agent 2: Blog management
blog_agent = ReActAgent.from_tools(
    toolkit.get_tools(service_filter="blog"), llm=llm
)

# Coordinate between agents
user_result = user_agent.chat("Create user Alice")
blog_result = blog_agent.chat(f"Create blog post for {user_result}")

Error Handling

from go_micro_llamaindex import GoMicroToolkit, GoMicroError

try:
    toolkit = GoMicroToolkit.from_gateway("http://localhost:3000")
    tools = toolkit.get_tools()
except GoMicroError as e:
    print(f"Error: {e}")

Advanced Configuration

from go_micro_llamaindex import GoMicroToolkit, GoMicroConfig

config = GoMicroConfig(
    gateway_url="http://localhost:3000",
    auth_token="your-token",
    timeout=30,
    retry_count=3,
    retry_delay=1.0,
    verify_ssl=True,
)

toolkit = GoMicroToolkit(config)
tools = toolkit.get_tools()

API Reference

GoMicroToolkit

Main class for interacting with Go Micro services.

Methods

from_gateway(gateway_url, auth_token=None, **kwargs) - Create toolkit from MCP gateway
get_tools(service_filter=None, name_pattern=None, include=None, exclude=None) - Get LlamaIndex tools
refresh() - Refresh tool list from gateway
call_tool(tool_name, arguments) - Call a tool directly
list_tools() - Get raw list of available tools

GoMicroConfig

Configuration for the toolkit.

Parameters

gateway_url (str) - MCP gateway URL
auth_token (str, optional) - Bearer authentication token
timeout (int) - Request timeout in seconds (default: 30)
retry_count (int) - Number of retries (default: 3)
retry_delay (float) - Delay between retries in seconds (default: 1.0)
verify_ssl (bool) - Verify SSL certificates (default: True)

Requirements

Python 3.8+
llama-index-core >= 0.10.0
requests >= 2.31.0
pydantic >= 2.0.0

Development

Setup

git clone https://github.com/micro/go-micro
cd go-micro/contrib/go-micro-llamaindex

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=go_micro_llamaindex

# Run specific test
pytest tests/test_toolkit.py

Code Formatting

# Format code
black go_micro_llamaindex tests

# Check types
mypy go_micro_llamaindex

# Lint
ruff check go_micro_llamaindex

Examples

See the examples directory for complete examples:

basic_agent.py - Simple ReAct agent
rag_with_services.py - RAG combined with microservices

Troubleshooting

Gateway Connection Issues

If you can't connect to the MCP gateway:

Verify the gateway is running:

curl http://localhost:3000/health

Check the gateway URL is correct
Verify firewall settings

Authentication Errors

If you get authentication errors:

Verify your token is valid
Check the token has required scopes
Review gateway logs for details

Tool Discovery Issues

If tools aren't being discovered:

List services from gateway:

curl http://localhost:3000/mcp/tools

Verify services are registered
Check service metadata is correct

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

Apache 2.0 - See LICENSE for details.

Support

GitHub Discussions: https://github.com/micro/go-micro/discussions
Discord: https://discord.gg/G8Gk5j3uXr

README.md

LlamaIndex Go Micro Integration