Content
# ModelContextProtocolClients.jl
A Julia client for the Model Context Protocol (MCP) that allows communication with various MCP servers. This package simplifies integrating AI tools into your Julia applications through a consistent interface.
# What is MCP Client?
This is an MCP Client that is able to start a MCP server or connect to an SSE MCP server.
So with this MCPClient anybody can query the `tools usage` for services that describe the RPC call format for the LLM and you can `forward the JSON RPC calls` generated by the LLM.
That simple.
MCPClientCollector is a list of the `MCPClient`s. Simple dict wrap that manage them as a group.
## Features
- Connect to multiple MCP servers simultaneously with multiple MCP client
- Manage tool discovery and invocation
- Support for Python and Node.js based MCP servers
- Environment variable handling for secure credential management
- Automatic server installation support
- Automatic MCP server discovery in directories
- Multiple transport layer support:
- stdio (local processes)
- Server-Sent Events (SSE)
## Installation
```julia
using Pkg
Pkg.add("ModelContextProtocolClients")
```
## SSE Example
```julia
using ModelContextProtocolClients
client = MCPClient("https://mcp.bitte.ai/sse", :sse)
tools = list_tools(client)
println(tools)
```
## STDIO Example with collector
```julia
!isdir("mcp/servers") && run(`git clone https://github.com/modelcontextprotocol/servers.git mcp/servers`)
# Create a server collector
collector = MCPClientCollector()
# Add a Puppeteer server
add_server(collector, "puppeteer", "mcp/servers/src/puppeteer/dist/index.js", setup_command=`bash -c "cd mcp/servers/src/puppeteer && npm install && npm run build"`)
# Get available tools
tools = list_tools(collector, "puppeteer")
println([tool["name"] for tool in tools])
# Navigate to a website
response = call_tool(collector, "puppeteer", "puppeteer_navigate", Dict(
"url" => "https://example.com",
"allowDangerous" => true,
"launchOptions" => Dict("headless" => false)
))
# Click elements
call_tool(collector, "puppeteer", "puppeteer_click", Dict(
"selector" => "a:nth-of-type(2)" # Click the second link
))
# Clean up
disconnect_all(collector)
```
## Loading every MCP Servers from root folder
MCP.jl can automatically discover and load MCP servers from a directory structure. It supports both Node.js and Python projects, including those with pyproject.toml configuration.
```julia
using ModelContextProtocolClients
# Create a collector
collector = MCPClientCollector()
# Explore a directory containing MCP servers
explore_mcp_servers_in_directory(collector, "mcp/")
# List all loaded clients
using ModelContextProtocolClients: list_clients
list_clients(collector)
# Now you can use any of the discovered tools
tools = list_tools(collector, "some_discovered_server")
```
The `explore_mcp_servers_in_directory` function will:
1. Scan the specified directory for potential MCP servers
2. Detect project types (Node.js or Python)
3. Parse configuration files (package.json, pyproject.toml)
4. Set up appropriate commands to run the servers
5. Install dependencies if needed
6. Verify that each server provides MCP tools
## Loading from Configuration
You can also load servers from a configuration file that include STDIO or SSE servers:
```julia
using ModelContextProtocolClients
# Create a collector
collector = MCPClientCollector()
# Load from config file
load_mcp_servers_config(collector, "mcp.json")
```
Example mcp.json with different transport types:
```json
{
"mcp": {
"servers": {
"local_server": {
"command": "node",
"args": ["path/to/server.js"],
"env": {
"API_KEY": "your-api-key"
}
},
"sse_server": {
"url": "http://localhost:8080/sse",
"transport": "sse"
}
}
}
}
```
## Tested Servers
The ModelContextProtocolClients.jl should work with most of the servers that is in nodejs or python
ModelContextProtocolClients.jl has been tested with:
- **puppeteer**: Browser automation
- **time**: Timezone conversion services
- **coinmarket**: Cryptocurrency data
- **sentry**: Error monitoring
- **slack**: Messaging platform integration
- **web-browser**: Web browsing RAG
- **https://mcp.bitte.ai/sse**: Blockchain empowered by agents
## API Reference
- `MCPClientCollector()` - Create a new collector
- `add_server(collector, id, path, [env]; setup_command=nothing)` - Connect to a local MCP server
- `add_server(collector, id, url, transport_type)` - Connect to a remote MCP server via WebSocket or SSE
- `list_tools(collector, server_id)` - List available tools
- `call_tool(collector, server_id, tool_name, arguments)` - Execute a tool
- `disconnect_all(collector)` - Close all server connections
- `explore_mcp_servers_in_directory(collector, directory; exclude_patterns=[])` - Discover MCP servers in a directory
- `list_clients(collector)` - List all loaded MCP server IDs
## Examples
Check the `test` directory for complete examples:
- `test_puppeteer.jl` - Web browser automation
- `test_coinmarket.jl` - Crypto market data retrieval
- `test_websocket.jl` - WebSocket transport example
- `test_sse.jl` - SSE transport example
- `test.jl` - Basic server setup and configuration
## ROADMAP
- [x] NodeJS MCP server run by the ModelContextProtocolClients
- [x] Python MCP server run by the ModelContextProtocolClients
- [x] Other language MCP server to be run by ModelContextProtocolClients (you only need to setup it and then send the "run command")
- [x] MCP server exploration per folder
- [x] Initialization of the server could be automatized like installation and so on
- [ ] configuration deduction (So we should be able to know what are the required environment variables nd list them somehow) (I don't know where does this know but sounds like hardcoded...? https://claudedesktopconfiggenerator.com/)
- [x] Anthropic Desktop configuration could be used to initialize system
- [x] mcp.json
- [x] mcpServers
- [x] Remote MCP usage for SSE
- [x] Transport layer support:
- [x] stdio (so local servers should be supported)
- [x] SSE transportlayer support
- [ ] Websocket (partially ready... also we need examples to test... also could be similar to SSE)
- [ ] MCP Standard compliance https://modelcontextprotocol.io/ test/mcp.json.example also shows great stuffs.
- [ ] https://claudedesktopconfiggenerator.com/ how does this able to generate the ENV tag too??
Note we have this to create julia MCP servers: https://github.com/JuliaSMLM/ModelContextProtocol.jl
We don't care about the websocket MCP servers as there are too few from them. Most of them (>99%) are SSE and stdio. But could be easily ported from here if we find examples.
## Contributing
Contributions welcome! Please feel free to submit a Pull Request.
## License
MIT
