Skip to content

index.md

Latest commit

 

History

History
222 lines (177 loc) · 6.37 KB

index.md

File metadata and controls

222 lines (177 loc) · 6.37 KB

ModelContextProtocol.jl

Julia implementation of the Model Context Protocol (MCP), enabling seamless integration between AI applications and external data sources, tools, and services.

Features

  • ✅ Core MCP 2025-06-18 Protocol - Server-side implementation with tools, resources, and prompts
  • ✅ Multiple Transports - stdio (default) and HTTP with Server-Sent Events
  • ✅ Multi-Content Responses - Tools can return text, images, and embedded resources
  • ✅ Auto-Registration - Automatic component discovery from directory structure
  • ✅ Type-Safe - Leverages Julia's type system for robust implementations
  • ✅ Session Management - Secure session handling for HTTP transport

Note: This is a server-side implementation. Client features (roots, sampling), OAuth, and some optional features (elicitation, audio content) are not yet implemented.

Installation

using Pkg
Pkg.add("ModelContextProtocol")

Quick Start

Create a simple MCP server with a tool:

using ModelContextProtocol

# Create a server with a simple echo tool
server = mcp_server(
    name = "echo-server",
    version = "1.0.0",
    tools = [
        MCPTool(
            name = "echo",
            description = "Echo back the input message",
            parameters = [
                ToolParameter(
                    name = "message",
                    type = "string",
                    description = "Message to echo",
                    required = true
                )
            ],
            handler = (params) -> TextContent(text = params["message"])
        )
    ]
)

# Start the server (stdio transport by default)
start!(server)

Using HTTP Transport

For web-based integrations, use the HTTP transport:

# Create server with HTTP transport
server = mcp_server(
    name = "http-server",
    version = "1.0.0",
    tools = [...],  # Your tools here
    transport = HttpTransport(host = "127.0.0.1", port = 3000)
)

start!(server)

# Test with curl
# curl -X POST http://127.0.0.1:3000/ \
#   -H "Content-Type: application/json" \
#   -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Documentation Structure

Protocol Compliance

ModelContextProtocol.jl implements the MCP specification version 2025-06-18, including:

  • JSON-RPC 2.0 message protocol
  • Tool discovery and invocation
  • Resource management with subscriptions
  • Prompt templates with arguments
  • Session management for HTTP transport
  • Content negotiation and multi-format responses

Basic Concepts

Tools

Tools are functions that can be invoked by the LLM:

tool = MCPTool(
    name = "calculate",
    description = "Perform basic arithmetic",
    parameters = [
        ToolParameter(name = "a", type = "number", required = true),
        ToolParameter(name = "b", type = "number", required = true),
        ToolParameter(name = "op", type = "string", required = true)
    ],
    handler = function(params)
        a, b = params["a"], params["b"]
        result = if params["op"] == "+"
            a + b
        elseif params["op"] == "-"
            a - b
        elseif params["op"] == "*"
            a * b
        elseif params["op"] == "/"
            a / b
        else
            error("Unknown operation")
        end
        return TextContent(text = string(result))
    end
)

Resources

Resources provide data access to the LLM:

resource = MCPResource(
    uri = "file:///data/config.json",
    name = "Application Config",
    description = "Current application configuration",
    mime_type = "application/json",
    handler = function(uri)
        config_data = read("config.json", String)
        return TextResourceContents(
            uri = uri,
            text = config_data,
            mime_type = "application/json"
        )
    end
)

Prompts

Prompts are templates for generating conversations:

prompt = MCPPrompt(
    name = "code_review",
    description = "Request a code review",
    arguments = [
        PromptArgument(
            name = "language",
            description = "Programming language",
            required = true
        )
    ],
    handler = function(args)
        return [
            PromptMessage(
                role = user,
                content = TextContent(
                    text = "Please review this $(args["language"]) code for best practices."
                )
            )
        ]
    end
)

Testing Your Server

With MCP Inspector

Test your server using the official MCP Inspector:

# For stdio transport
npx @modelcontextprotocol/inspector stdio -- julia --project server.jl

# For HTTP transport
npx @modelcontextprotocol/inspector http://127.0.0.1:3000/

With curl (HTTP only)

# Initialize connection
curl -X POST http://127.0.0.1:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

# List available tools
curl -X POST http://127.0.0.1:3000/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id-from-init>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

Next Steps

Contributing

ModelContextProtocol.jl is part of the JuliaSMLM organization. Contributions are welcome! Please see our GitHub repository for issues and pull requests.

License

This project is licensed under the MIT License.