mcp

MCP (Model Context Protocol) server library for Kit — stdio and Streamable HTTP transports

Files

Dependencies

No Kit package dependencies.

Capabilities

This package requires the net capability. Pass --allow=net when building or running:

kit build --allow=net myfile.kit -o myfile
kit run --allow=net myfile.kit

Installation

kit add gitlab.com/kit-lang/packages/kit-mcp.git

Usage

Stdio Transport

Read JSON-RPC messages from stdin, write responses to stdout:

import Encoding.JSON
import StdIn

import Kit.MCP as MCP

main = fn(-env: Env) =>
  greet-handler = fn(-params) =>
    MCP.text-result "Hello from Kit MCP!"

  add-handler = fn(params) =>
    a = JSON.get-int params "a" ?? 0
    b = JSON.get-int params "b" ?? 0
    MCP.text-result (Int.to-string (a + b))

  greet-tool = MCP.tool "greet" "Returns a greeting" greet-handler
  add-tool = MCP.tool "add" "Add two numbers" add-handler

  srv = MCP.server "hello-kit" "0.1.0"
    |> MCP.register greet-tool
    |> MCP.register add-tool

  # Stdio transport loop
  loop = fn(state) =>
    input = StdIn.read-line
    match input
      | Ok line ->
          match MCP.handle-request srv line
            | Some response -> println response
            | None -> no-op
          loop state
      | Err _ -> no-op
  loop 0

main

Streamable HTTP Transport

Start an HTTP server that accepts JSON-RPC via POST:

import Kit.MCP as MCP

main = fn(-env: Env) =>
  srv = MCP.server "hello-kit-http" "0.1.0"
    |> MCP.register (MCP.tool "greet" "Returns a greeting" (fn(-params) => MCP.text-result "Hello!"))

  log-cfg = MCP.default-log-config
    |> MCP.with-log-level MCP.Debug
    |> MCP.with-log-format MCP.PrettyFmt

  match MCP.serve srv {host: "127.0.0.1", port: 8080} log-cfg
    | Ok _ -> println "Server stopped"
    | Err e -> println ("Server error: " ++ e)

main

API Reference

Server

Tools

Resources

Prompts

Logging

Log levels: MCP.Debug, MCP.Info, MCP.Warn, MCP.Error

Log formats: MCP.JsonFmt, MCP.PrettyFmt, MCP.CompactFmt

Log outputs: MCP.ToStdout, MCP.ToStderr

SSE

Development

Running Examples

Run examples with the interpreter:

kit run examples/hello-server.kit
kit run --allow=net examples/hello-sse-server.kit

Compile examples to a native binary:

kit build examples/hello-server.kit -o hello-server && ./hello-server
kit build --allow=net examples/hello-sse-server.kit -o hello-sse-server && ./hello-sse-server

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/mcp/, making it available for import as Kit.MCP in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

server

Create a new MCP server with a name and version.

String -> String -> MCPServer

register

Register a tool with the server.

MCPServer -> MCPTool -> MCPServer

tool

Create a tool definition with a name, description, and handler function.

String -> String -> (JSONValue -> JSONValue) -> MCPTool

with-schema

Return a new MCPTool with a custom inputSchema.

MCPTool -> JSONValue -> MCPTool

text-result

Helper to create a text content result for tool responses.

String -> JSONValue

resource

Create a resource definition with a URI, name, description, MIME type, and reader function.

String -> String -> String -> String -> (String -> String) -> MCPResource

register-resource

Register a resource with the server.

MCPServer -> MCPResource -> MCPServer

prompt

Create a prompt definition with a name, description, arguments, and handler function.

String -> String -> JSONValue -> (JSONValue -> JSONValue) -> MCPPrompt

prompt-arg

Helper to build a single prompt argument definition as JSONValue.

String -> String -> Bool -> JSONValue

register-prompt

Register a prompt with the server.

MCPServer -> MCPPrompt -> MCPServer

user-message

Create a user message for prompt responses.

String -> JSONValue

assistant-message

Create an assistant message for prompt responses.

String -> JSONValue

handle-request

Handle a single JSON-RPC message string from the client. Returns Some(response-string) for requests, or None for notifications.

MCPServer -> String -> Option String

serve

Start an MCP server with Streamable HTTP transport. Creates an HTTP server and handles JSON-RPC requests via POST. Blocks until the server encounters an error.

MCPServer -> {host: String, port: Int} -> LogConfig -> Result Unit String

format-sse-event

Format data as a Server-Sent Event string.

String -> String -> String

default-log-config

Default MCP log configuration: compact format, stderr, info level. Use with-log-level, with-log-format, and with-log-output to customize.

with-log-level

Set the minimum log level for MCP server logging.

LogConfig -> Level -> LogConfig

with-log-format

Set the output format for MCP server logging.

LogConfig -> Format -> LogConfig

with-log-output

Set the output target for MCP server logging.

LogConfig -> Output -> LogConfig

Debug

Debug log level — verbose protocol details, request bodies

Info

Info log level — request summaries, connection events

Warn

Warn log level — recoverable issues

Error

Error log level — failures

JsonFmt

JSON format — structured JSON output

PrettyFmt

Pretty format — colored, human-readable output

CompactFmt

Compact format — concise, uncolored output

ToStdout

Log to stdout

ToStderr

Log to stderr

server

Create a new MCP server with a name and version.

String -> String -> MCPServer

register

Register a tool with the server.

MCPServer -> MCPTool -> MCPServer

tool

Create a tool definition with a default empty inputSchema.

String -> String -> (JSONValue -> JSONValue) -> MCPTool

with-schema

Return a new MCPTool with a custom inputSchema.

MCPTool -> JSONValue -> MCPTool

text-result

Helper to create a text content result for tool responses.

String -> JSONValue

resource

Create a resource definition.

String -> String -> String -> String -> (String -> String) -> MCPResource

register-resource

Register a resource with the server.

MCPServer -> MCPResource -> MCPServer

prompt

Create a prompt definition.

String -> String -> JSONValue -> (JSONValue -> JSONValue) -> MCPPrompt

prompt-arg

Helper to build a single prompt argument definition as JSONValue.

String -> String -> Bool -> JSONValue

register-prompt

Register a prompt with the server.

MCPServer -> MCPPrompt -> MCPServer

user-message

Create a user message for prompt responses.

String -> JSONValue

assistant-message

Create an assistant message for prompt responses.

String -> JSONValue

handle-request

Handle a single JSON-RPC message string from the client. Returns Some(response-string) for requests, or None for notifications.

MCPServer -> String -> Option String

format-sse-event

Format data as a Server-Sent Event string.

String -> String -> String

default-log-config

Default MCP log configuration: compact format, stderr, info level.

serve

Start an MCP server with HTTP transport. Supports both SSE (GET for event stream + POST /message) and Streamable HTTP (POST / for JSON-RPC). Blocks until the server encounters an error.

MCPServer -> {host: String, port: Int} -> LogConfig -> Result Unit String

srv = MCP.server "my-server" "1.0"
  |> MCP.register (MCP.tool "greet" "A greeting" handler)
MCP.serve srv {host: "127.0.0.1", port: 8080} MCP.default-log-config

MCPTool

An MCP tool with a name, description, input schema, and handler function. The handler receives the tool arguments as JSONValue and returns a JSONValue result.

MCPResource

An MCP resource with a URI, name, description, MIME type, and reader function. The reader receives the URI as a String and returns the resource content as a String.

MCPPrompt

An MCP prompt template with a name, description, arguments definition, and handler. Arguments is a JSONArray of {name, description, required} objects. The handler receives the arguments as JSONValue and returns a JSONArray of messages.

MCPServer

An MCP server configuration with a name, version, and registered tools, resources, and prompts.