Server Types

Server Types

Core types used in MCPHub's native server implementation.

Native Server Definition

---@class NativeServer
---@field name string Server name
---@field displayName string Display name
---@field capabilities MCPCapabilities Server capabilities

---@class MCPCapabilities
---@field tools? MCPTool[] List of tools
---@field resources? MCPResource[] List of resources
---@field resourceTemplates? MCPResourceTemplate[] List of resource templates
---@field prompts? MCPPrompt[] List of prompts

Tool Types

---@class MCPTool
---@field name string Tool identifier
---@field description string|fun():string Tool description or function returning description
---@field inputSchema? table|fun():table JSON Schema for input validation or function returning schema
---@field handler fun(req: ToolRequest, res: ToolResponse): nil | table Tool handler function

---@class ToolRequest
---@field params table Tool arguments (validated against inputSchema)
---@field tool MCPTool Complete tool definition including dynamic fields
---@field server NativeServer Server instance
---@field caller table Additional context from caller
---@field editor_info EditorInfo Current editor state

---@class ToolResponse
---@field text fun(self: ToolResponse, text: string): ToolResponse Add text content
---@field image fun(self: ToolResponse, data: string, mime: string): ToolResponse Add image content
---@field resource fun(self: ToolResponse, resource: MCPResourceContent): ToolResponse Add resource content
---@field error fun(self: ToolResponse, message: string, details?: table): table Send error response
---@field send fun(self: ToolResponse, result?: table): table Send response

Prompt Types

---@class MCPPrompt
---@field name string Prompt identifier
---@field description string|fun():string Prompt description or function returning description
---@field arguments? { name: string, description?: string,required?:boolean , default?: string}[] Optional argument definitions
---@field handler fun(req: PromptRequest, res: PromptResponse): nil | table Prompt handler function

---@class PromptRequest
---@field params table Prompt arguments from user
---@field prompt MCPPrompt Complete prompt definition including dynamic fields
---@field server NativeServer Server instance
---@field caller table Additional context from caller
---@field editor_info EditorInfo Current editor state

---@class PromptResponse
---@field text fun(self: PromptResponse, text: string): PromptResponse Add text message
---@field image fun(self: PromptResponse, data: string, mime: string): PromptResponse Add image message
---@field audio fun(self: PromptResponse, data: string, mime: string): PromptResponse Add audio message
---@field blob fun(self: PromptResponse, data: string, mime: string): PromptResponse Add blob message
---@field resource fun(self: PromptResponse, resource: MCPResourceContent): PromptResponse Add resource message
---@field user fun(self: PromptResponse): PromptResponse Set role to user
---@field llm fun(self: PromptResponse): PromptResponse Set role to assistant/LLM
---@field system fun(self: PromptResponse): PromptResponse Set role to system
---@field error fun(self: PromptResponse, message: string, details?: table): table Send error response
---@field send fun(self: PromptResponse, result?: table): table Send response

Resource Types

---@class MCPResource
---@field name? string Resource identifier
---@field description? string|fun():string Resource description or function returning description
---@field mimeType? string Resource MIME type (e.g., "text/plain")
---@field uri string Static URI (e.g., "system://info")
---@field handler fun(req: ResourceRequest, res: ResourceResponse): nil | table Resource handler function

---@class MCPResourceTemplate
---@field name? string Template identifier
---@field description? string|fun():string Template description or function returning description
---@field mimeType? string Template MIME type (e.g., "text/plain")
---@field uriTemplate string URI with parameters (e.g., "buffer://{bufnr}/lines")
---@field handler fun(req: ResourceRequest, res: ResourceResponse): nil | table Template handler function

---@class ResourceRequest
---@field params table<string, string> Template parameters from URI
---@field uri string Complete requested URI
---@field uriTemplate string|nil Original template pattern if from template
---@field resource MCPResource|MCPResourceTemplate Complete resource definition including dynamic fields
---@field server NativeServer Server instance
---@field caller table Additional context from caller
---@field editor_info EditorInfo Current editor state

---@class ResourceResponse
---@field text fun(self: ResourceResponse, text: string, mime?: string): ResourceResponse Add text content
---@field blob fun(self: ResourceResponse, data: string, mime?: string): ResourceResponse Add binary content
---@field image fun(self: ResourceResponse, data: string, mime: string): ResourceResponse Add image content
---@field error fun(self: ResourceResponse, message: string, details?: table): table Send error response
---@field send fun(self: ResourceResponse, result?: table): table Send response

Content Types

---@alias MCPResourceContent { uri: string, text?: string, blob?: string, mimeType: string }

---@alias MCPContent { 
---  type: "text"|"image"|"audio"|"resource", 
---  text?: string, 
---  data?: string, 
---  resource?: MCPResourceContent, 
---  mimeType?: string 
---}

---@alias MCPMessage {
---  role: "user"|"assistant"|"system",
---  content: MCPContent
---}

Usage Notes

1. Dynamic Fields

   • Descriptions and schemas can be functions
   • Functions evaluated at runtime for dynamic content

2. Resource URIs

   • Static URIs: resource://path
   • Template URIs: resource://{param}/path
   • Make sure any params are enclosed in {} in order to parse them correctly

3. Response Types

   • Tools: Content array with text/image/resource
   • Resources: URI-based content with MIME type
   • Prompts: Message array with roles and content
   • All responses must call :send()

4. Error Handling

   • Use res:error() for failure cases
   • Includes optional details for debugging

5. Prompt Roles

   • user: Input messages
   • assistant/llm: AI responses
   • system: System messages/errors