re-export MCP functionality for dependents

The contents of the mcpserver/ directory were written by Claude, in another
project, to provide the desired exported interface without having to
reimplement or copy logic.  This makes character better for embedding.
(Not great, there's a lot of CLI assumptions so our dependency chain is not
as small as it could be, but ... marginally better).

The changes to mcpstdio were mostly what Claude wanted, but rather than have
both `toolEntry` and `ToolEntry` I unified them.

Author: philpennock

internal/mcpstdio/mcpstdio.go

@@ -22,6 +22,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"slices"
 )
 
 // Handler processes a single tool call.  It receives the tool arguments as
@@ -35,17 +36,19 @@ type ToolDef struct {
 	InputSchema json.RawMessage // hand-written JSON Schema object
 }
 
-type toolEntry struct {
-	def     ToolDef
-	handler Handler
+// ToolEntry exposes a registered tool's definition and handler for use by
+// the public mcpserver bridge package.
+type ToolEntry struct {
+	Def     ToolDef
+	Handler Handler
 }
 
 // Server is a tool-only MCP stdio server.
 type Server struct {
 	name         string
 	version      string
 	instructions string
-	tools        []toolEntry
+	tools        []ToolEntry
 	byName       map[string]int
 }
 
@@ -69,9 +72,25 @@ func (s *Server) SetInstructions(text string) {
 // AddTool registers a tool.  Registration order is preserved in tools/list.
 func (s *Server) AddTool(def ToolDef, h Handler) {
 	s.byName[def.Name] = len(s.tools)
-	s.tools = append(s.tools, toolEntry{def: def, handler: h})
+	s.tools = append(s.tools, ToolEntry{Def: def, Handler: h})
 }
 
+// Tools returns a snapshot of all registered tools in registration order.
+func (s *Server) Tools() []ToolEntry {
+	return slices.Clone(s.tools)
+}
+
+// Instructions returns the instructions string, or "" if none was set.
+func (s *Server) Instructions() string {
+	return s.instructions
+}
+
+// Name returns the server name.
+func (s *Server) Name() string { return s.name }
+
+// Version returns the server version.
+func (s *Server) Version() string { return s.version }
+
 // ServeStdio runs the MCP server on os.Stdin / os.Stdout.
 func (s *Server) ServeStdio(ctx context.Context) error {
 	return s.ServeConn(ctx, os.Stdin, os.Stdout)
@@ -206,9 +225,9 @@ func (s *Server) handleToolsList(w io.Writer, id json.RawMessage) {
 	items := make([]toolItem, len(s.tools))
 	for i, t := range s.tools {
 		items[i] = toolItem{
-			Name:        t.def.Name,
-			Description: t.def.Description,
-			InputSchema: t.def.InputSchema,
+			Name:        t.Def.Name,
+			Description: t.Def.Description,
+			InputSchema: t.Def.InputSchema,
 		}
 	}
 	writeResponse(w, id, result{Tools: items})
@@ -239,7 +258,7 @@ func (s *Server) handleToolsCall(ctx context.Context, w io.Writer, id json.RawMe
 		IsError bool          `json:"isError,omitempty"`
 	}
 
-	text, err := s.tools[idx].handler(ctx, p.Arguments)
+	text, err := s.tools[idx].Handler(ctx, p.Arguments)
 	if err != nil {
 		writeResponse(w, id, callResult{
 			Content: []contentItem{{Type: "text", Text: err.Error()}},

mcpserver/README.md

@@ -0,0 +1,11 @@
+character :: mcpserver
+======================
+
+This sub-package is not used by the character CLI tool itself.
+
+This is a bridge to export a limited supportable API for use when character is
+a library used by other tools.
+
+If you're exploring the character code-base, you can mostly ignore this.  You
+just need to ensure that the tests continue to pass without changing the API
+incompatibly.

mcpserver/mcpserver.go

@@ -0,0 +1,108 @@
+// Copyright © 2026 Phil Pennock.
+// All rights reserved, except as granted under license.
+// Licensed per file LICENSE.txt
+
+// Package mcpserver re-exports the MCP server core from internal/mcpstdio so
+// that consumers outside this module can inspect registered tools and re-use
+// handlers in alternative transports (e.g. HTTP via the official MCP SDK).
+//
+// The Server type embeds the internal implementation; this package adds only
+// the [ToolRegistration] type and the [Server.Tools] accessor.
+package mcpserver
+
+import (
+	"context"
+	"io"
+
+	"github.com/philpennock/character/internal/mcpstdio"
+)
+
+// Handler processes a single tool call.  It receives the tool arguments as
+// raw JSON and returns a result string, or an error if the call failed.
+//
+// This is a type alias for the internal handler signature so that callers
+// outside this module can reference it without importing internal packages.
+type Handler = mcpstdio.Handler
+
+// ToolDef describes a single MCP tool for registration and for tools/list.
+//
+// This is a type alias for the internal tool definition so that callers
+// outside this module can reference it without importing internal packages.
+type ToolDef = mcpstdio.ToolDef
+
+// ToolRegistration pairs a [ToolDef] with its [Handler], allowing external
+// consumers to iterate over all registered tools and re-register them on a
+// different transport.
+type ToolRegistration struct {
+	ToolDef
+	Handler Handler
+}
+
+// Server wraps [mcpstdio.Server] and exposes the registered tools for
+// external consumption.  All stdio-serving methods delegate directly.
+type Server struct {
+	inner *mcpstdio.Server
+}
+
+// NewServer creates a Server with the given name and version strings (used in
+// the InitializeResult serverInfo).
+func NewServer(name, version string) *Server {
+	return &Server{inner: mcpstdio.NewServer(name, version)}
+}
+
+// SetInstructions sets the instructions string returned in the
+// InitializeResult.  Per MCP 2025-03-26 §Lifecycle, clients MAY surface this
+// to the model to guide tool discovery and usage.
+func (s *Server) SetInstructions(text string) {
+	s.inner.SetInstructions(text)
+}
+
+// Instructions returns the instructions string, or "" if none was set.
+func (s *Server) Instructions() string {
+	return s.inner.Instructions()
+}
+
+// AddTool registers a tool.  Registration order is preserved in tools/list
+// and in the slice returned by [Server.Tools].
+func (s *Server) AddTool(def ToolDef, h Handler) {
+	s.inner.AddTool(def, h)
+}
+
+// Tools returns a snapshot of all registered tools in registration order.
+// The returned slice is a copy; callers may safely retain it.
+func (s *Server) Tools() []ToolRegistration {
+	inner := s.inner.Tools()
+	out := make([]ToolRegistration, len(inner))
+	for i, t := range inner {
+		out[i] = ToolRegistration{
+			ToolDef: t.Def,
+			Handler: t.Handler,
+		}
+	}
+	return out
+}
+
+// Name returns the server name (as reported in InitializeResult serverInfo).
+func (s *Server) Name() string { return s.inner.Name() }
+
+// Version returns the server version (as reported in InitializeResult
+// serverInfo).
+func (s *Server) Version() string { return s.inner.Version() }
+
+// ServeStdio runs the MCP server on os.Stdin / os.Stdout.
+func (s *Server) ServeStdio(ctx context.Context) error {
+	return s.inner.ServeStdio(ctx)
+}
+
+// ServeConn runs the MCP server on the given reader/writer.  It is the
+// testable entry point; production code typically calls [Server.ServeStdio].
+func (s *Server) ServeConn(ctx context.Context, r io.Reader, w io.Writer) error {
+	return s.inner.ServeConn(ctx, r, w)
+}
+
+// Inner returns the underlying [mcpstdio.Server].  This is intended for use
+// by code within this module that needs direct access; external consumers
+// should use [Server.Tools] instead.
+func (s *Server) Inner() *mcpstdio.Server {
+	return s.inner
+}

mcpserver/mcpserver_test.go

@@ -0,0 +1,129 @@
+// Copyright © 2026 Phil Pennock.
+// All rights reserved, except as granted under license.
+// Licensed per file LICENSE.txt
+
+package mcpserver
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"testing"
+)
+
+func echoHandler(_ context.Context, args json.RawMessage) (string, error) {
+	return string(args), nil
+}
+
+func failHandler(_ context.Context, _ json.RawMessage) (string, error) {
+	return "", fmt.Errorf("intentional failure")
+}
+
+func TestNewServerAccessors(t *testing.T) {
+	s := NewServer("test", "v0.1.0")
+	if s.Name() != "test" {
+		t.Errorf("Name() = %q, want %q", s.Name(), "test")
+	}
+	if s.Version() != "v0.1.0" {
+		t.Errorf("Version() = %q, want %q", s.Version(), "v0.1.0")
+	}
+	if s.Instructions() != "" {
+		t.Errorf("Instructions() = %q, want empty", s.Instructions())
+	}
+
+	s.SetInstructions("do things")
+	if s.Instructions() != "do things" {
+		t.Errorf("Instructions() = %q, want %q", s.Instructions(), "do things")
+	}
+}
+
+func TestToolsEmpty(t *testing.T) {
+	s := NewServer("test", "v1")
+	if tools := s.Tools(); len(tools) != 0 {
+		t.Errorf("Tools() returned %d entries on empty server, want 0", len(tools))
+	}
+}
+
+func TestAddToolAndTools(t *testing.T) {
+	s := NewServer("test", "v1")
+	s.AddTool(ToolDef{
+		Name:        "echo",
+		Description: "echoes arguments",
+		InputSchema: json.RawMessage(`{"type":"object"}`),
+	}, echoHandler)
+	s.AddTool(ToolDef{
+		Name:        "fail",
+		Description: "always fails",
+		InputSchema: json.RawMessage(`{"type":"object"}`),
+	}, failHandler)
+
+	tools := s.Tools()
+	if len(tools) != 2 {
+		t.Fatalf("Tools() returned %d entries, want 2", len(tools))
+	}
+
+	// Registration order preserved.
+	if tools[0].Name != "echo" {
+		t.Errorf("tools[0].Name = %q, want %q", tools[0].Name, "echo")
+	}
+	if tools[1].Name != "fail" {
+		t.Errorf("tools[1].Name = %q, want %q", tools[1].Name, "fail")
+	}
+
+	// Handlers are callable through the bridge type.
+	result, err := tools[0].Handler(context.Background(), json.RawMessage(`{"x":1}`))
+	if err != nil {
+		t.Fatalf("echo handler error: %v", err)
+	}
+	if result != `{"x":1}` {
+		t.Errorf("echo handler result = %q, want %q", result, `{"x":1}`)
+	}
+
+	_, err = tools[1].Handler(context.Background(), nil)
+	if err == nil {
+		t.Fatal("fail handler should return error")
+	}
+}
+
+func TestToolsReturnsCopy(t *testing.T) {
+	s := NewServer("test", "v1")
+	s.AddTool(ToolDef{Name: "a", Description: "a"}, echoHandler)
+
+	t1 := s.Tools()
+	t2 := s.Tools()
+	t1[0].Name = "mutated"
+	if t2[0].Name != "a" {
+		t.Error("Tools() returned shared backing, not independent copies")
+	}
+}
+
+func TestToolRegistrationFields(t *testing.T) {
+	s := NewServer("test", "v1")
+	schema := json.RawMessage(`{"type":"object","properties":{"n":{"type":"string"}}}`)
+	s.AddTool(ToolDef{
+		Name:        "greet",
+		Description: "says hello",
+		InputSchema: schema,
+	}, echoHandler)
+
+	tr := s.Tools()[0]
+	if tr.Name != "greet" {
+		t.Errorf("Name = %q", tr.Name)
+	}
+	if tr.Description != "says hello" {
+		t.Errorf("Description = %q", tr.Description)
+	}
+	if string(tr.InputSchema) != string(schema) {
+		t.Errorf("InputSchema = %s", tr.InputSchema)
+	}
+	if tr.Handler == nil {
+		t.Error("Handler is nil")
+	}
+}
+
+func TestInnerNotNil(t *testing.T) {
+	s := NewServer("test", "v1")
+	if s.Inner() == nil {
+		t.Error("Inner() returned nil")
+	}
+}