amcs/internal/mcpserver/server.go

package mcpserver

import (
	"log/slog"
	"net/http"
	"strings"

	"github.com/modelcontextprotocol/go-sdk/mcp"

	"git.warky.dev/wdevs/amcs/internal/config"
	"git.warky.dev/wdevs/amcs/internal/tools"
	amcsllm "git.warky.dev/wdevs/amcs/llm"
)

const (
	serverTitle      = "Avalon Memory Crystal Server"
	serverWebsiteURL = "https://git.warky.dev/wdevs/amcs"
)

type ToolSet struct {
	Version       *tools.VersionTool
	Capture       *tools.CaptureTool
	Search        *tools.SearchTool
	List          *tools.ListTool
	Stats         *tools.StatsTool
	Get           *tools.GetTool
	Update        *tools.UpdateTool
	Delete        *tools.DeleteTool
	Archive       *tools.ArchiveTool
	Projects      *tools.ProjectsTool
	Context       *tools.ContextTool
	Recall        *tools.RecallTool
	Summarize     *tools.SummarizeTool
	Links         *tools.LinksTool
	Files         *tools.FilesTool
	Backfill      *tools.BackfillTool
	Reparse       *tools.ReparseMetadataTool
	RetryMetadata *tools.RetryMetadataTool
	Maintenance   *tools.MaintenanceTool
	Skills        *tools.SkillsTool
	ChatHistory   *tools.ChatHistoryTool
	Describe      *tools.DescribeTool
}

// Handlers groups the HTTP handlers produced for an MCP server instance.
type Handlers struct {
	// StreamableHTTP is the primary MCP handler (always non-nil).
	StreamableHTTP http.Handler
	// SSE is the SSE transport handler; nil when SSEPath is empty.
	// SSE is the de facto transport for MCP over the internet and is required by most hosted MCP clients.
	SSE http.Handler
}

// New builds the StreamableHTTP MCP handler. It is a convenience wrapper
// around NewHandlers for callers that only need the primary transport.
func New(cfg config.MCPConfig, logger *slog.Logger, toolSet ToolSet, onSessionClosed func(string)) (http.Handler, error) {
	h, err := NewHandlers(cfg, logger, toolSet, onSessionClosed)
	if err != nil {
		return nil, err
	}
	return h.StreamableHTTP, nil
}

// NewHandlers builds MCP HTTP handlers for both transports.
// SSE is nil when cfg.SSEPath is empty.
func NewHandlers(cfg config.MCPConfig, logger *slog.Logger, toolSet ToolSet, onSessionClosed func(string)) (Handlers, error) {
	instructions := cfg.Instructions
	if instructions == "" {
		instructions = string(amcsllm.MemoryInstructions)
	}

	server := mcp.NewServer(&mcp.Implementation{
		Name:       cfg.ServerName,
		Title:      serverTitle,
		Version:    cfg.Version,
		WebsiteURL: serverWebsiteURL,
		Icons:      buildServerIcons(cfg.PublicURL),
	}, &mcp.ServerOptions{
		Instructions: instructions,
	})

	for _, register := range []func(*mcp.Server, *slog.Logger, ToolSet) error{
		registerSystemTools,
		registerThoughtTools,
		registerProjectTools,
		registerFileTools,
		registerMaintenanceTools,
		registerSkillTools,
		registerChatHistoryTools,
		registerDescribeTools,
	} {
		if err := register(server, logger, toolSet); err != nil {
			return Handlers{}, err
		}
	}

	opts := &mcp.StreamableHTTPOptions{
		JSONResponse:   true,
		SessionTimeout: cfg.SessionTimeout,
	}
	if onSessionClosed != nil {
		opts.EventStore = newCleanupEventStore(mcp.NewMemoryEventStore(nil), onSessionClosed)
	}

	h := Handlers{
		StreamableHTTP: mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server {
			return server
		}, opts),
	}

	if strings.TrimSpace(cfg.SSEPath) != "" {
		h.SSE = mcp.NewSSEHandler(func(*http.Request) *mcp.Server {
			return server
		}, nil)
	}

	return h, nil
}

// buildServerIcons returns icon definitions referencing the server's own /images/icon.png endpoint.
// Returns nil when publicURL is empty so the icons field is omitted from the MCP identity.
func buildServerIcons(publicURL string) []mcp.Icon {
	if strings.TrimSpace(publicURL) == "" {
		return nil
	}
	base := strings.TrimRight(publicURL, "/")
	return []mcp.Icon{
		{Source: base + "/images/icon.png", MIMEType: "image/png"},
	}
}

func registerSystemTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "get_version_info",
		Description: "Build version, commit, and date.",
	}, toolSet.Version.GetInfo); err != nil {
		return err
	}
	return nil
}

func registerThoughtTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "capture_thought",
		Description: "Store a thought; embeddings and metadata extracted async.",
	}, toolSet.Capture.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "search_thoughts",
		Description: "Semantic search; falls back to full-text if no embeddings.",
	}, toolSet.Search.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_thoughts",
		Description: "List recent thoughts with optional metadata filters.",
	}, toolSet.List.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "thought_stats",
		Description: "Counts and top metadata buckets for stored thoughts.",
	}, toolSet.Stats.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "get_thought",
		Description: "Retrieve a full thought by id.",
	}, toolSet.Get.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "update_thought",
		Description: "Update thought content or merge metadata.",
	}, toolSet.Update.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "delete_thought",
		Description: "Hard-delete a thought by id.",
	}, toolSet.Delete.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "archive_thought",
		Description: "Hide a thought from default search and listing.",
	}, toolSet.Archive.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "summarize_thoughts",
		Description: "LLM summary of a filtered set of thoughts.",
	}, toolSet.Summarize.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "recall_context",
		Description: "Semantic + recency context for prompt injection; falls back to full-text.",
	}, toolSet.Recall.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "link_thoughts",
		Description: "Create a typed relationship between two thoughts.",
	}, toolSet.Links.Link); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "related_thoughts",
		Description: "Explicit links and semantic neighbours; falls back to full-text.",
	}, toolSet.Links.Related); err != nil {
		return err
	}
	return nil
}

func registerProjectTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "create_project",
		Description: "Create a named project container for thoughts.",
	}, toolSet.Projects.Create); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_projects",
		Description: "List projects and their current thought counts.",
	}, toolSet.Projects.List); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "set_active_project",
		Description: "Set session's active project. Pass project per call if client is stateless.",
	}, toolSet.Projects.SetActive); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "get_active_project",
		Description: "Return session's active project. Pass project per call if client is stateless.",
	}, toolSet.Projects.GetActive); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "get_project_context",
		Description: "Recent and semantic context for a project; falls back to full-text.",
	}, toolSet.Context.Handle); err != nil {
		return err
	}
	return nil
}

func registerFileTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	server.AddResourceTemplate(&mcp.ResourceTemplate{
		Name:        "stored_file",
		URITemplate: "amcs://files/{id}",
		Description: "A stored file. Read a file's raw binary content by its id. Use load_file for metadata.",
	}, toolSet.Files.ReadResource)

	if err := addTool(server, logger, &mcp.Tool{
		Name:        "upload_file",
		Description: "Stage a file; returns amcs://files/{id}. content_path for large/binary, content_base64 for ≤10 MB. Link now or pass URI to save_file.",
	}, toolSet.Files.Upload); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "save_file",
		Description: "Store and optionally link a file. content_base64 (≤10 MB) or content_uri from upload_file. >10 MB: use upload_file first.",
	}, toolSet.Files.Save); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "load_file",
		Description: "Fetch file metadata and content by id (UUID or amcs://files/{id}); includes embedded MCP resource.",
	}, toolSet.Files.Load); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_files",
		Description: "List stored files, optionally filtered by thought, project, or kind.",
	}, toolSet.Files.List); err != nil {
		return err
	}
	return nil
}

func registerMaintenanceTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "backfill_embeddings",
		Description: "Generate missing embeddings. Run after model switch or bulk import.",
	}, toolSet.Backfill.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "reparse_thought_metadata",
		Description: "Re-extract metadata from thought content.",
	}, toolSet.Reparse.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "retry_failed_metadata",
		Description: "Retry pending/failed metadata extraction.",
	}, toolSet.RetryMetadata.Handle); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "add_maintenance_task",
		Description: "Create a recurring or one-time home maintenance task.",
	}, toolSet.Maintenance.AddTask); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "log_maintenance",
		Description: "Log completed maintenance; updates next due date.",
	}, toolSet.Maintenance.LogWork); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "get_upcoming_maintenance",
		Description: "List maintenance tasks due within the next N days.",
	}, toolSet.Maintenance.GetUpcoming); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "search_maintenance_history",
		Description: "Search the maintenance log by task name, category, or date range.",
	}, toolSet.Maintenance.SearchHistory); err != nil {
		return err
	}
	return nil
}

func registerSkillTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "add_skill",
		Description: "Store an agent skill (instruction or capability prompt).",
	}, toolSet.Skills.AddSkill); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "remove_skill",
		Description: "Delete an agent skill by id.",
	}, toolSet.Skills.RemoveSkill); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_skills",
		Description: "List all agent skills, optionally filtered by tag.",
	}, toolSet.Skills.ListSkills); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "add_guardrail",
		Description: "Store an agent guardrail (constraint or safety rule).",
	}, toolSet.Skills.AddGuardrail); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "remove_guardrail",
		Description: "Delete an agent guardrail by id.",
	}, toolSet.Skills.RemoveGuardrail); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_guardrails",
		Description: "List all agent guardrails, optionally filtered by tag or severity.",
	}, toolSet.Skills.ListGuardrails); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "add_project_skill",
		Description: "Link a skill to a project. Pass project if client is stateless.",
	}, toolSet.Skills.AddProjectSkill); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "remove_project_skill",
		Description: "Unlink a skill from a project. Pass project if client is stateless.",
	}, toolSet.Skills.RemoveProjectSkill); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_project_skills",
		Description: "Skills for a project. Load at session start; only add new if none returned. Pass project if stateless.",
	}, toolSet.Skills.ListProjectSkills); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "add_project_guardrail",
		Description: "Link a guardrail to a project. Pass project if client is stateless.",
	}, toolSet.Skills.AddProjectGuardrail); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "remove_project_guardrail",
		Description: "Unlink a guardrail from a project. Pass project if client is stateless.",
	}, toolSet.Skills.RemoveProjectGuardrail); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_project_guardrails",
		Description: "Guardrails for a project. Load at session start; only add new if none returned. Pass project if stateless.",
	}, toolSet.Skills.ListProjectGuardrails); err != nil {
		return err
	}
	return nil
}

func registerChatHistoryTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "save_chat_history",
		Description: "Save chat messages with optional title, summary, channel, agent, and project.",
	}, toolSet.ChatHistory.SaveChatHistory); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "get_chat_history",
		Description: "Fetch chat history by UUID or session_id.",
	}, toolSet.ChatHistory.GetChatHistory); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "list_chat_histories",
		Description: "List chat histories; filter by project, channel, agent_id, session_id, or days.",
	}, toolSet.ChatHistory.ListChatHistories); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "delete_chat_history",
		Description: "Delete a chat history by id.",
	}, toolSet.ChatHistory.DeleteChatHistory); err != nil {
		return err
	}
	return nil
}

func registerDescribeTools(server *mcp.Server, logger *slog.Logger, toolSet ToolSet) error {
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "describe_tools",
		Description: "Call first each session. All tools with categories and usage notes. Categories: system, thoughts, projects, files, admin, maintenance, skills, chat, meta.",
	}, toolSet.Describe.Describe); err != nil {
		return err
	}
	if err := addTool(server, logger, &mcp.Tool{
		Name:        "annotate_tool",
		Description: "Save usage notes for a tool; returned by describe_tools. Empty string clears.",
	}, toolSet.Describe.Annotate); err != nil {
		return err
	}
	return nil
}

// BuildToolCatalog returns the static catalog of all registered MCP tools.
// Pass this to tools.NewDescribeTool when assembling the ToolSet.
func BuildToolCatalog() []tools.ToolEntry {
	return []tools.ToolEntry{
		// system
		{Name: "get_version_info", Description: "Return the server build version information, including version, tag name, commit, and build date.", Category: "system"},

		// thoughts
		{Name: "capture_thought", Description: "Store a thought with generated embeddings and extracted metadata. The thought is saved immediately even if metadata extraction times out; pending thoughts are retried in the background.", Category: "thoughts"},
		{Name: "search_thoughts", Description: "Search stored thoughts by semantic similarity. Falls back to Postgres full-text search automatically when no embeddings exist for the active model.", Category: "thoughts"},
		{Name: "list_thoughts", Description: "List recent thoughts with optional metadata filters.", Category: "thoughts"},
		{Name: "thought_stats", Description: "Get counts and top metadata buckets across stored thoughts.", Category: "thoughts"},
		{Name: "get_thought", Description: "Retrieve a full thought by id.", Category: "thoughts"},
		{Name: "update_thought", Description: "Update thought content or merge metadata.", Category: "thoughts"},
		{Name: "delete_thought", Description: "Hard-delete a thought by id.", Category: "thoughts"},
		{Name: "archive_thought", Description: "Archive a thought so it is hidden from default search and listing.", Category: "thoughts"},
		{Name: "summarize_thoughts", Description: "Produce an LLM prose summary of a filtered or searched set of thoughts.", Category: "thoughts"},
		{Name: "recall_context", Description: "Recall semantically relevant and recent context for prompt injection. Combines vector similarity with recency. Falls back to full-text search when no embeddings exist.", Category: "thoughts"},
		{Name: "link_thoughts", Description: "Create a typed relationship between two thoughts.", Category: "thoughts"},
		{Name: "related_thoughts", Description: "Retrieve explicit links and semantic neighbours for a thought. Falls back to full-text search when no embeddings exist.", Category: "thoughts"},

		// projects
		{Name: "create_project", Description: "Create a named project container for thoughts.", Category: "projects"},
		{Name: "list_projects", Description: "List projects and their current thought counts.", Category: "projects"},
		{Name: "set_active_project", Description: "Set the active project for the current MCP session. Requires a stateful MCP client that reuses the same session across calls. If your client does not preserve sessions, pass project explicitly to each tool instead.", Category: "projects"},
		{Name: "get_active_project", Description: "Return the active project for the current MCP session. If your client does not preserve MCP sessions, pass project explicitly to project-scoped tools instead of relying on this.", Category: "projects"},
		{Name: "get_project_context", Description: "Get recent and semantic context for a project. Uses the explicit project when provided, otherwise the active MCP session project. Falls back to full-text search when no embeddings exist.", Category: "projects"},

		// files
		{Name: "upload_file", Description: "Stage a file and get an amcs://files/{id} resource URI. Use content_path (absolute server-side path, no size limit) for large or binary files, or content_base64 (≤10 MB) for small files. Pass thought_id/project to link immediately, or omit and pass the URI to save_file later.", Category: "files"},
		{Name: "save_file", Description: "Store a file and optionally link it to a thought. Use content_base64 (≤10 MB) for small files, or content_uri (amcs://files/{id} from a prior upload_file) for previously staged files. For files larger than 10 MB, use upload_file with content_path first. If the goal is to retain the artifact, store the file directly instead of reading or summarising it first.", Category: "files"},
		{Name: "load_file", Description: "Load a stored file by id. Returns metadata, base64 content, and an embedded MCP binary resource at amcs://files/{id}. Prefer the embedded resource when your client supports it. The id field accepts a bare UUID or full amcs://files/{id} URI.", Category: "files"},
		{Name: "list_files", Description: "List stored files, optionally filtered by thought, project, or kind.", Category: "files"},

		// admin
		{Name: "backfill_embeddings", Description: "Generate missing embeddings for stored thoughts using the active embedding model. Run this after switching embedding models or importing thoughts that have no vectors.", Category: "admin"},
		{Name: "reparse_thought_metadata", Description: "Re-extract and normalize metadata for stored thoughts from their content.", Category: "admin"},
		{Name: "retry_failed_metadata", Description: "Retry metadata extraction for thoughts still marked pending or failed.", Category: "admin"},

		// maintenance
		{Name: "add_maintenance_task", Description: "Create a recurring or one-time home maintenance task.", Category: "maintenance"},
		{Name: "log_maintenance", Description: "Log completed maintenance work; automatically updates the task's next due date.", Category: "maintenance"},
		{Name: "get_upcoming_maintenance", Description: "List maintenance tasks due within the next N days.", Category: "maintenance"},
		{Name: "search_maintenance_history", Description: "Search the maintenance log by task name, category, or date range.", Category: "maintenance"},

		// skills
		{Name: "add_skill", Description: "Store a reusable agent skill (behavioural instruction or capability prompt).", Category: "skills"},
		{Name: "remove_skill", Description: "Delete an agent skill by id.", Category: "skills"},
		{Name: "list_skills", Description: "List all agent skills, optionally filtered by tag.", Category: "skills"},
		{Name: "add_guardrail", Description: "Store a reusable agent guardrail (constraint or safety rule).", Category: "skills"},
		{Name: "remove_guardrail", Description: "Delete an agent guardrail by id.", Category: "skills"},
		{Name: "list_guardrails", Description: "List all agent guardrails, optionally filtered by tag or severity.", Category: "skills"},
		{Name: "add_project_skill", Description: "Link an agent skill to a project. Pass project explicitly when your client does not preserve MCP sessions.", Category: "skills"},
		{Name: "remove_project_skill", Description: "Unlink an agent skill from a project. Pass project explicitly when your client does not preserve MCP sessions.", Category: "skills"},
		{Name: "list_project_skills", Description: "List all skills linked to a project. Call this at the start of every project session to load agent behaviour instructions before generating new ones. Only create new skills if none are returned. Pass project explicitly when your client does not preserve MCP sessions.", Category: "skills"},
		{Name: "add_project_guardrail", Description: "Link an agent guardrail to a project. Pass project explicitly when your client does not preserve MCP sessions.", Category: "skills"},
		{Name: "remove_project_guardrail", Description: "Unlink an agent guardrail from a project. Pass project explicitly when your client does not preserve MCP sessions.", Category: "skills"},
		{Name: "list_project_guardrails", Description: "List all guardrails linked to a project. Call this at the start of every project session to load agent constraints before generating new ones. Only create new guardrails if none are returned. Pass project explicitly when your client does not preserve MCP sessions.", Category: "skills"},

		// chat
		{Name: "save_chat_history", Description: "Save a chat session's message history for later retrieval. Stores messages with optional title, summary, channel, agent, and project metadata.", Category: "chat"},
		{Name: "get_chat_history", Description: "Retrieve a saved chat history by its UUID or session_id. Returns the full message list.", Category: "chat"},
		{Name: "list_chat_histories", Description: "List saved chat histories with optional filters: project, channel, agent_id, session_id, or recent days.", Category: "chat"},
		{Name: "delete_chat_history", Description: "Permanently delete a saved chat history by id.", Category: "chat"},

		// meta
		{Name: "describe_tools", Description: "Call this first in every session. Returns all available MCP tools with names, descriptions, categories, and your accumulated usage notes. Filter by category to narrow results. Available categories: system, thoughts, projects, files, admin, household, maintenance, calendar, meals, crm, skills, chat, meta.", Category: "meta"},
		{Name: "annotate_tool", Description: "Persist usage notes, gotchas, or workflow patterns for a specific tool. Notes survive across sessions and are returned by describe_tools. Call this whenever you discover something non-obvious about a tool's behaviour. Pass an empty string to clear notes.", Category: "meta"},
	}
}