raku -sdk

The Raku MCP SDK provides a way to build MCP servers and clients using the Raku programming language. With this SDK you can expose resources, tools, and prompts that integrate with the Model Context Protocol, enabling AI hosts and clients to discover and interact with these capabilities. The SDK includes a fluent builder API, tool and resource annotations, and a set of patterns for constructing JSON-RPC 2.0 compliant endpoints over multiple transports. Typical usage involves implementing MCP endpoints in Raku, registering them with a server, and then running the server so that clients can initialize, enumerate, and invoke the exposed capabilities.

To use the SDK, write Raku code that defines the resources, tools, and prompts your server offers. Use the provided builder API to compose endpoints, specify input/output schemas, and attach metadata such as tool icons, names, and descriptions. You can then run the server (via your preferred Raku runtime) and connect a client application or an IDE integration that speaks MCP. The SDK supports common MCP features like JSON-RPC 2.0 messaging, stdio and HTTP transports, logging, notifications, tool execution, and structured content for tool outputs. Developers can also leverage experimental extensions and the builder annotations to customize how resources and prompts are constructed and serialized.

If you are building an application that interacts with large language models or other AI tools, this SDK makes it straightforward to expose a consistent set of capabilities (tools, resources, prompts) and to handle lifecycle events such as progress updates, cancellations, and subscriptions. The included tooling guidance covers how to annotate implementations, how to expose tool metadata, and how to structure responses using the output schemas defined by MCP.

Prerequisites:

• A working Raku (Rakudo) environment installed on your system
• zef, the Raku module manager, available in your PATH
• Git to clone the repository

1. Install a Raku compiler and tooling

• Install Rakudo and MoarVM from your platform's package manager or from the official sources.
• Ensure the 'rakudo' and 'zef' commands are available in your shell.

2. Clone the MCP SDK repository

• git clone https://github.com/wkusnierczyk/raku-mcp-sdk.git
• cd raku-mcp-sdk

3. Install SDK dependencies

• zef install . --force
• This will install the MCP SDK modules and any declared dependencies.

4. Run or develop locally

• Follow project-specific examples to run a sample MCP server or build your own using the builder API.

• If there are example scripts, you can execute them with the Raku interpreter, e.g.:

  raku examples/server.pl

5. Validate installation

• Run available tests or example workflows provided in the repository to ensure MCP endpoints are wired correctly.

Notes:

• The SDK is designed to be used within Raku tooling, so integration steps focus on compiling and running Raku code that exposes MCP capabilities rather than a traditional runtime binary.

Tips and common considerations:

• The SDK targets MCP specification compatibility; keep an eye on the MCP version referenced by your server to ensure client interop.
• Use the provided builder API and annotations to keep your server logic clean and maintainable; this helps in large projects with many tools and resources.
• Transports supported by MCP can include Stdio and HTTP; choose the transport that best fits your deployment scenario.
• When exposing tools, make sure to provide clear metadata (name, description, icons) to improve user experience in IDEs and clients.
• If you enable experimental features or extensions, test thoroughly across your client applications as behavior may differ from stable components.
• Consider adding logging and progress notifications to aid in debugging and user feedback during long-running operations.