mcpkit

hawk-mcpkit

Shared MCP server scaffolding for the hawk ecosystem.

mcpkit wraps mark3labs/mcp-go with the construction, transports, and handler helpers that every hawk-ecosystem engine (inspect, sight, ...) would otherwise duplicate. Repos declare their tools and handlers; mcpkit does the rest.

Tagline: Shared MCP server scaffolding for the hawk ecosystem.

Install

go get github.com/GrayCodeAI/hawk-mcpkit

Usage

package main

import (
	"context"

	mcpkit "github.com/GrayCodeAI/hawk-mcpkit"
	mcplib "github.com/mark3labs/mcp-go/mcp"
)

func main() {
	s := mcpkit.New("mytool", "0.1.0")

	s.AddTool(
		mcplib.NewTool("greet",
			mcplib.WithDescription("Greets a person by name."),
			mcplib.WithString("name", mcplib.Required(), mcplib.Description("Who to greet")),
		),
		func(ctx context.Context, req mcplib.CallToolRequest) (*mcplib.CallToolResult, error) {
			name := mcpkit.StrArg(req, "name")
			if name == "" {
				return mcplib.NewToolResultError("name is required"), nil
			}
			return mcpkit.JSONResult(map[string]string{"greeting": "hello " + name})
		},
	)

	// stdio transport:
	_ = s.ServeStdio()
	// or streamable HTTP at http://localhost:8080/mcp:
	// _ = s.ServeHTTP(":8080")
}

Quick Reference

Architecture

hawk-mcpkit Server
├── wraps mark3labs/mcp-go MCPServer
├── AddTool() registers tools + handlers
├── ServeStdio() → stdin/stdout transport
├── ServeHTTP(addr) → streamable HTTP at /mcp
├── StrArg() → extract string arguments
└── JSONResult() → marshal values as JSON text results

API Reference

Server

Handler Helpers

Ecosystem

hawk-mcpkit is a foundation repo in the hawk-eco mono-ecosystem:

Engines that serve MCP (sight, inspect) import hawk-mcpkit; it never imports them back.

Ecosystem Boundaries

Rules that keep this repo at the foundation layer:

• Zero hawk-eco dependencies. This repo must never import hawk, any engine (eyrie, yaad, tok, trace, sight, inspect), any SDK, or hawk-core-contracts. Its only non-stdlib dependency is upstream mark3labs/mcp-go. make boundaries (also run in CI) enforces this with scripts/check-ecosystem-boundaries.sh.
• Implementation-free of product logic. This repo holds MCP server scaffolding only — no hawk orchestration, no engine-specific behavior, no provider logic.
• Consumers, not dependents. Engines that serve MCP (sight, inspect) import hawk-mcpkit; it never imports them back.

If you need a hawk-ecosystem type here, that's a sign it belongs in the consuming engine instead, not in this repo.

License

MIT — see LICENSE.