nimwire/core

This page is generated from the module’s exported API and ## documentation comments.

Typed protocol values and JSON-RPC validation.

Constants

mcpProtocolVersion

mcpProtocolVersion = "2026-07-28"

View source

mcpJsonRpcVersion

mcpJsonRpcVersion = "2.0"

View source

mcpParseErrorCode

mcpParseErrorCode = -32700

View source

mcpInvalidRequestCode

mcpInvalidRequestCode = -32600

View source

mcpMethodNotFoundCode

mcpMethodNotFoundCode = -32601

View source

mcpInvalidParamsCode

mcpInvalidParamsCode = -32602

View source

mcpInternalErrorCode

mcpInternalErrorCode = -32603

View source

mcpRequestCancelledCode

mcpRequestCancelledCode = -32800

View source

mcpServerBusyCode

mcpServerBusyCode = -32029

View source

mcpHeaderMismatchCode

mcpHeaderMismatchCode = -32020

View source

mcpUnsupportedProtocolVersionCode

mcpUnsupportedProtocolVersionCode = -32022

View source

mcpMissingRequiredClientCapabilityCode

mcpMissingRequiredClientCapabilityCode = -32021

View source

mcpDefaultMaxMessageBytes

mcpDefaultMaxMessageBytes = 1048576

View source

mcpDefaultMaxNestingDepth

mcpDefaultMaxNestingDepth = 64

View source

mcpDefaultCompletionLimit

mcpDefaultCompletionLimit = 100

View source

mcpMetaProtocolVersionKey

mcpMetaProtocolVersionKey = "io.modelcontextprotocol/protocolVersion"

View source

mcpMetaClientInfoKey

mcpMetaClientInfoKey = "io.modelcontextprotocol/clientInfo"

View source

mcpMetaClientCapabilitiesKey

mcpMetaClientCapabilitiesKey = "io.modelcontextprotocol/clientCapabilities"

View source

mcpMetaTraceContextKey

mcpMetaTraceContextKey = "io.modelcontextprotocol/traceContext"

View source

mcpMetaLogLevelKey

mcpMetaLogLevelKey = "io.modelcontextprotocol/logLevel"

View source

mcpMetaProgressTokenKey

mcpMetaProgressTokenKey = "progressToken"

View source

Types

McpError

McpError = object of CatchableError
  code*: int
  data*: JsonNode
  retryable*: bool

View source

McpIdKind

McpIdKind = enum
  mcpStringId, mcpIntegerId, mcpNullId

View source

McpId

McpId = object
  case kind*: McpIdKind
  of mcpStringId:
    stringValue*: string
  of mcpIntegerId:
    integerValue*: int64
  of mcpNullId:
    nil

View source

McpClientInfo

McpClientInfo = object
  name*: string
  version*: string
  extraFields*: JsonNode

View source

McpClientCapabilities

Capability names are extensible, so their object is retained as JSON.

McpClientCapabilities = object
  fields*: JsonNode

View source

McpTraceContext

McpTraceContext = object
  traceparent*: string
  tracestate*: string
  baggage*: string
  extensionFields*: JsonNode

View source

McpLogLevel

McpLogLevel = enum
  mcpLogDebug, mcpLogInfo, mcpLogNotice, mcpLogWarning, mcpLogError,
  mcpLogCritical, mcpLogAlert, mcpLogEmergency

View source

McpRequestMeta

McpRequestMeta = object
  protocolVersion*: string
  hasClientInfo*: bool
  clientInfo*: McpClientInfo
  clientCapabilities*: McpClientCapabilities
  hasTraceContext*: bool
  traceContext*: McpTraceContext
  hasLogLevel*: bool
  logLevel*: McpLogLevel
  hasProgressToken*: bool
  progressToken*: McpId
  extensionMetadata*: JsonNode

View source

McpParams

values contains method-specific params; _meta is decoded into meta.

McpParams = object
  values*: JsonNode
  meta*: McpRequestMeta

View source

McpInputRequest

A server-to-client request embedded in an input_required result.

McpInputRequest = object
  methodName*: string
  params*: JsonNode
  extraFields*: JsonNode

View source

McpResultType

McpResultType = enum
  mcpComplete, mcpInputRequired, mcpTask

View source

McpWireResult

McpWireResult = object
  resultType*: McpResultType ## Result fields are method-specific and retained for forward compatibility.
  fields*: JsonNode

View source

McpTypedError

McpTypedError = object
  code*: string
  message*: string
  details*: JsonNode
  retryable*: bool

View source

McpResult

A typed handler result. It is converted to McpToolResult at the wire boundary and never leaks protocol-specific fields into application code.

McpResult[T] = object
  case isError*: bool
  of false:
    value*: T
  of true:
    error*: McpTypedError

View source

McpRpcError

McpRpcError = object
  code*: int
  message*: string
  data*: JsonNode
  extraFields*: JsonNode

View source

McpRequestKind

McpRequestKind = enum
  mcpRequest, mcpNotification

View source

McpRpcRequest

McpRpcRequest = object
  case kind*: McpRequestKind
  of mcpRequest:
    id*: McpId
  of mcpNotification:
    nil
  methodName*: string
  params*: McpParams
  extraFields*: JsonNode

View source

McpRpcResponse

McpRpcResponse = object
  id*: McpId
  result*: McpWireResult
  extraFields*: JsonNode

View source

McpRpcErrorResponse

McpRpcErrorResponse = object
  id*: McpId
  error*: McpRpcError
  extraFields*: JsonNode

View source

McpJsonRpcMessageKind

McpJsonRpcMessageKind = enum
  mcpRequestMessage, mcpNotificationMessage, mcpResponseMessage, mcpErrorMessage

View source

McpJsonRpcMessage

McpJsonRpcMessage = object
  case kind*: McpJsonRpcMessageKind
  of mcpRequestMessage, mcpNotificationMessage:
    request*: McpRpcRequest
  of mcpResponseMessage:
    response*: McpRpcResponse
  of mcpErrorMessage:
    errorResponse*: McpRpcErrorResponse

View source

McpToolResult

Handler-facing result before it is wrapped in a JSON-RPC result.

McpToolResult = object
  content*: JsonNode
  structuredContent*: JsonNode
  isError*: bool
  retryable*: bool

View source

Procedures

newMcpError

proc newMcpError(message: string; code = mcpInvalidParamsCode;
                 data: JsonNode = nil): ref McpError {.raises: [], tags: [],
    forbids: [].}

Returns: ref McpError.

Arguments

Name	Type	Default
message	string
code	inferred	mcpInvalidParamsCode
data	JsonNode	nil

View source

retryableMcpError

proc retryableMcpError(message: string; code = mcpInternalErrorCode;
                       data: JsonNode = nil): ref McpError {.raises: [],
    tags: [], forbids: [].}

Returns: ref McpError.

Arguments

Name	Type	Default
message	string
code	inferred	mcpInternalErrorCode
data	JsonNode	nil

View source

mcpResult

proc mcpResult[T](value: T): McpResult[T]

Type parameters: T.

Returns: McpResult[T].

Arguments

Name	Type	Default
value	T

View source

mcpResultError

proc mcpResultError[T](code, message: string; details: JsonNode = nil;
                       retryable = false): McpResult[T]

Type parameters: T.

Returns: McpResult[T].

Arguments

Name	Type	Default
code	string
message	string
details	JsonNode	nil
retryable	inferred	false

View source

mcpFailure

proc mcpFailure[T](message: string; details: JsonNode = nil; retryable = false): McpResult[
    T]

Type parameters: T.

Returns: McpResult[T].

Arguments

Name	Type	Default
message	string
details	JsonNode	nil
retryable	inferred	false

View source

requireObject

proc requireObject(node: JsonNode; context: string): JsonNode {.
    raises: [McpError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
node	JsonNode
context	string

View source

requiredString

proc requiredString(node: JsonNode; key, context: string): string {.
    raises: [KeyError, McpError], tags: [], forbids: [].}

Returns: string.

Arguments

Name	Type	Default
node	JsonNode
key	string
context	string

View source

parseMcpId

proc parseMcpId(node: JsonNode; allowNull = false): McpId {.raises: [McpError],
    tags: [], forbids: [].}

Returns: McpId.

Arguments

Name	Type	Default
node	JsonNode
allowNull	inferred	false

View source

toJson (overload 1)

proc toJson(id: McpId): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
id	McpId

View source

==

proc `==`(left, right: McpId): bool {.raises: [], tags: [], forbids: [].}

Returns: bool.

Arguments

Name	Type	Default
left	McpId
right	McpId

View source

resultTypeName

proc resultTypeName(resultType: McpResultType): string {.raises: [], tags: [],
    forbids: [].}

Returns: string.

Arguments

Name	Type	Default
resultType	McpResultType

View source

newMcpResult

proc newMcpResult(resultType: McpResultType; fields: JsonNode = nil): McpWireResult {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: McpWireResult.

Arguments

Name	Type	Default
resultType	McpResultType
fields	JsonNode	nil

View source

parseMcpResult

proc parseMcpResult(node: JsonNode): McpWireResult {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: McpWireResult.

Arguments

Name	Type	Default
node	JsonNode

View source

toJson (overload 2)

proc toJson(value: McpWireResult): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpWireResult

View source

newMcpRpcError

proc newMcpRpcError(code: int; message: string; data: JsonNode = nil;
                    extraFields: JsonNode = nil): McpRpcError {.
    raises: [McpError], tags: [], forbids: [].}

Returns: McpRpcError.

Arguments

Name	Type	Default
code	int
message	string
data	JsonNode	nil
extraFields	JsonNode	nil

View source

parseMcpRpcError

proc parseMcpRpcError(node: JsonNode): McpRpcError {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: McpRpcError.

Arguments

Name	Type	Default
node	JsonNode

View source

toJson (overload 3)

proc toJson(value: McpRpcError): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpRpcError

View source

logLevelName

proc logLevelName(level: McpLogLevel): string {.raises: [], tags: [],
    forbids: [].}

Returns: string.

Arguments

Name	Type	Default
level	McpLogLevel

View source

toJson (overload 4)

proc toJson(value: McpClientInfo): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpClientInfo

View source

toJson (overload 5)

proc toJson(value: McpClientCapabilities): JsonNode {.raises: [], tags: [],
    forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpClientCapabilities

View source

toJson (overload 6)

proc toJson(value: McpTraceContext): JsonNode {.raises: [], tags: [],
    forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpTraceContext

View source

parseMcpRequestMeta

proc parseMcpRequestMeta(node: JsonNode): McpRequestMeta {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: McpRequestMeta.

Arguments

Name	Type	Default
node	JsonNode

View source

toJson (overload 7)

proc toJson(value: McpRequestMeta): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpRequestMeta

View source

parseMcpParams

proc parseMcpParams(node: JsonNode): McpParams {.raises: [McpError, KeyError],
    tags: [], forbids: [].}

Returns: McpParams.

Arguments

Name	Type	Default
node	JsonNode

View source

toJson (overload 8)

proc toJson(value: McpParams): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpParams

View source

validateMethod

proc validateMethod(methodName: string) {.raises: [McpError], tags: [],
    forbids: [].}

Arguments

Name	Type	Default
methodName	string

View source

parseMcpRequest

proc parseMcpRequest(node: JsonNode; maxNestingDepth = mcpDefaultMaxNestingDepth): McpRpcRequest {.
    raises: [McpError, Exception, KeyError], tags: [RootEffect], forbids: [].}

Returns: McpRpcRequest.

Arguments

Name	Type	Default
node	JsonNode
maxNestingDepth	inferred	mcpDefaultMaxNestingDepth

View source

parseMcpResponse

proc parseMcpResponse(node: JsonNode): McpRpcResponse {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: McpRpcResponse.

Arguments

Name	Type	Default
node	JsonNode

View source

parseMcpErrorResponse

proc parseMcpErrorResponse(node: JsonNode): McpRpcErrorResponse {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: McpRpcErrorResponse.

Arguments

Name	Type	Default
node	JsonNode

View source

parseMcpMessage (overload 1)

proc parseMcpMessage(node: JsonNode; maxNestingDepth = mcpDefaultMaxNestingDepth): McpJsonRpcMessage {.
    raises: [McpError, Exception, KeyError], tags: [RootEffect], forbids: [].}

Returns: McpJsonRpcMessage.

Arguments

Name	Type	Default
node	JsonNode
maxNestingDepth	inferred	mcpDefaultMaxNestingDepth

View source

parseMcpMessage (overload 2)

proc parseMcpMessage(payload: string;
                     maxMessageBytes = mcpDefaultMaxMessageBytes;
                     maxNestingDepth = mcpDefaultMaxNestingDepth): McpJsonRpcMessage {.
    raises: [McpError, McpError, Exception, KeyError],
    tags: [ReadIOEffect, WriteIOEffect, RootEffect], forbids: [].}

Returns: McpJsonRpcMessage.

Arguments

Name	Type	Default
payload	string
maxMessageBytes	inferred	mcpDefaultMaxMessageBytes
maxNestingDepth	inferred	mcpDefaultMaxNestingDepth

View source

successResponse

proc successResponse(id: McpId; value: McpWireResult): McpJsonRpcMessage {.
    raises: [], tags: [], forbids: [].}

Returns: McpJsonRpcMessage.

Arguments

Name	Type	Default
id	McpId
value	McpWireResult

View source

errorResponse

proc errorResponse(id: McpId; code: int; message: string; data: JsonNode = nil): McpJsonRpcMessage {.
    raises: [McpError], tags: [], forbids: [].}

Returns: McpJsonRpcMessage.

Arguments

Name	Type	Default
id	McpId
code	int
message	string
data	JsonNode	nil

View source

requestIdOrNull

proc requestIdOrNull(node: JsonNode): McpId {.raises: [KeyError], tags: [],
    forbids: [].}

Returns: McpId.

Arguments

Name	Type	Default
node	JsonNode

View source

toJson (overload 9)

proc toJson(value: McpRpcRequest): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpRpcRequest

View source

toJson (overload 10)

proc toJson(value: McpRpcResponse): JsonNode {.raises: [], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpRpcResponse

View source

toJson (overload 11)

proc toJson(value: McpRpcErrorResponse): JsonNode {.raises: [], tags: [],
    forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpRpcErrorResponse

View source

toJson (overload 12)

proc toJson(value: McpJsonRpcMessage): JsonNode {.raises: [], tags: [],
    forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpJsonRpcMessage

View source

textResult

proc textResult(text: string; isError = false): McpToolResult {.raises: [],
    tags: [], forbids: [].}

Returns: McpToolResult.

Arguments

Name	Type	Default
text	string
isError	inferred	false

View source

jsonResult

proc jsonResult(value: JsonNode; isError = false): McpToolResult {.raises: [],
    tags: [], forbids: [].}

Returns: McpToolResult.

Arguments

Name	Type	Default
value	JsonNode
isError	inferred	false

View source

textContent

proc textContent(text: string; annotations: JsonNode = nil): JsonNode {.
    raises: [McpError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
text	string
annotations	JsonNode	nil

View source

imageContent

proc imageContent(data, mimeType: string; annotations: JsonNode = nil): JsonNode {.
    raises: [McpError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
data	string
mimeType	string
annotations	JsonNode	nil

View source

audioContent

proc audioContent(data, mimeType: string; annotations: JsonNode = nil): JsonNode {.
    raises: [McpError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
data	string
mimeType	string
annotations	JsonNode	nil

View source

resourceLinkContent

proc resourceLinkContent(uri, name: string; mimeType = ""; title = "";
                         description = ""; size: int64 = -1;
                         annotations: JsonNode = nil): JsonNode {.
    raises: [McpError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
uri	string
name	string
mimeType	inferred	""
title	inferred	""
description	inferred	""
size	int64	-1
annotations	JsonNode	nil

View source

embeddedResourceContent

proc embeddedResourceContent(resource: JsonNode; annotations: JsonNode = nil): JsonNode {.
    raises: [McpError, KeyError], tags: [], forbids: [].}

Returns: JsonNode.

Arguments

Name	Type	Default
resource	JsonNode
annotations	JsonNode	nil

View source

newMcpToolResult

proc newMcpToolResult(content: JsonNode; structuredContent: JsonNode = nil;
                      isError = false): McpToolResult {.raises: [McpError],
    tags: [], forbids: [].}

Returns: McpToolResult.

Arguments

Name	Type	Default
content	JsonNode
structuredContent	JsonNode	nil
isError	inferred	false

View source

structuredResult

proc structuredResult(value: JsonNode; isError = false): McpToolResult {.
    raises: [], tags: [], forbids: [].}

Returns: McpToolResult.

Arguments

Name	Type	Default
value	JsonNode
isError	inferred	false

View source

typedResultJson

proc typedResultJson[T](value: T): JsonNode

Type parameters: T.

Returns: JsonNode.

Arguments

Name	Type	Default
value	T

View source

toMcpToolResult

proc toMcpToolResult[T](value: McpResult[T]): McpToolResult

Type parameters: T.

Returns: McpToolResult.

Arguments

Name	Type	Default
value	McpResult[T]

View source

toJson (overload 13)

proc toJson[T](value: McpResult[T]): JsonNode

Type parameters: T.

Returns: JsonNode.

Arguments

Name	Type	Default
value	McpResult[T]

View source