hyperguild/ingestion/internal/mcp/handlers.go

package mcp

import (
	"context"
	"encoding/json"
	"fmt"
	"path/filepath"
	"strings"
	"time"

	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
	"github.com/mathiasbq/hyperguild/ingestion/internal/session"
)

// tools returns the tool descriptors. Handler bodies for each tool are filled
// in subsequent tasks; this file currently only provides the descriptors.
func (s *Server) tools() []map[string]any {
	str := func(desc string) map[string]any {
		return map[string]any{"type": "string", "description": desc}
	}
	int_ := func(desc string) map[string]any {
		return map[string]any{"type": "integer", "description": desc}
	}
	schema := func(required []string, props map[string]any) json.RawMessage {
		b, _ := json.Marshal(map[string]any{
			"type": "object", "required": required, "properties": props,
		})
		return b
	}

	return []map[string]any{
		{
			"name":        "brain_query",
			"description": "BM25 full-text search across brain/knowledge/ and brain/wiki/ markdown files.",
			"inputSchema": schema([]string{"query"}, map[string]any{
				"query": str("search terms"),
				"limit": int_("max results, default 5"),
			}),
		},
		{
			"name":        "brain_write",
			"description": "Write a raw knowledge note to brain/knowledge/.",
			"inputSchema": schema([]string{"content"}, map[string]any{
				"content":  str("markdown content"),
				"filename": str("optional filename"),
				"type":     str("optional frontmatter type"),
				"domain":   str("optional frontmatter domain"),
			}),
		},
		{
			"name":        "brain_ingest_raw",
			"description": "Ingest pre-structured pages into the brain wiki, bypassing the LLM extraction step.",
			"inputSchema": schema([]string{"source", "pages"}, map[string]any{
				"source":  str("source name"),
				"pages":   map[string]any{"type": "array"},
				"dry_run": map[string]any{"type": "boolean"},
			}),
		},
		{
			"name":        "brain_ingest",
			"description": "Ingest content into the brain wiki via the LLM extraction pipeline.",
			"inputSchema": schema([]string{}, map[string]any{
				"content": str("raw content; required when path is empty"),
				"source":  str("source name; required when path is empty"),
				"path":    str("file path; mutually exclusive with content+source"),
				"dry_run": map[string]any{"type": "boolean"},
			}),
		},
		{
			"name":        "session_log",
			"description": "Append a structured entry to brain/sessions/<session_id>.jsonl.",
			"inputSchema": schema([]string{"session_id"}, map[string]any{
				"session_id":   str("session identifier"),
				"skill":        str("skill name"),
				"phase":        str("phase within the skill"),
				"project_root": str("absolute project root"),
				"final_status": str("ok | error | skipped"),
				"file_path":    str("optional file produced"),
				"model_used":   str("optional model identifier"),
				"duration_ms":  int_("optional duration in ms"),
				"message":      str("optional free-text"),
			}),
		},
	}
}

type brainQueryArgs struct {
	Query string `json:"query"`
	Limit int    `json:"limit,omitempty"`
}

func (s *Server) brainQuery(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
	var a brainQueryArgs
	if err := json.Unmarshal(args, &a); err != nil {
		return nil, fmt.Errorf("parse args: %w", err)
	}
	if a.Query == "" {
		return nil, fmt.Errorf("query is required")
	}
	if a.Limit == 0 {
		a.Limit = 5
	}
	results, err := search.Query(s.brainDir, a.Query, a.Limit)
	if err != nil {
		return nil, fmt.Errorf("search: %w", err)
	}
	return json.Marshal(map[string]any{"results": results})
}

type brainWriteArgs struct {
	Content  string `json:"content"`
	Filename string `json:"filename,omitempty"`
	Type     string `json:"type,omitempty"`
	Domain   string `json:"domain,omitempty"`
}

func (s *Server) brainWrite(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
	var a brainWriteArgs
	if err := json.Unmarshal(args, &a); err != nil {
		return nil, fmt.Errorf("parse args: %w", err)
	}
	relPath, err := api.WriteNote(s.brainDir, a.Content, a.Filename, a.Type, a.Domain)
	if err != nil {
		return nil, err
	}
	return json.Marshal(map[string]string{"path": relPath})
}

type brainIngestRawArgs struct {
	Source string             `json:"source"`
	Pages  []pipeline.RawPage `json:"pages"`
	DryRun bool               `json:"dry_run,omitempty"`
}

func (s *Server) brainIngestRaw(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
	var a brainIngestRawArgs
	if err := json.Unmarshal(args, &a); err != nil {
		return nil, fmt.Errorf("parse args: %w", err)
	}
	if a.Source == "" {
		return nil, fmt.Errorf("source is required")
	}
	if len(a.Pages) == 0 {
		return nil, fmt.Errorf("pages must be non-empty")
	}
	result, err := pipeline.RunRaw(s.brainDir, a.Source, a.Pages, a.DryRun)
	if err != nil {
		return nil, fmt.Errorf("ingest: %w", err)
	}
	pages := result.Pages
	if pages == nil {
		pages = []string{}
	}
	warnings := result.Warnings
	if warnings == nil {
		warnings = []string{}
	}
	return json.Marshal(map[string]any{"pages": pages, "warnings": warnings})
}

type brainIngestArgs struct {
	Content string `json:"content,omitempty"`
	Source  string `json:"source,omitempty"`
	Path    string `json:"path,omitempty"`
	DryRun  bool   `json:"dry_run,omitempty"`
}

func (s *Server) brainIngest(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
	var a brainIngestArgs
	if err := json.Unmarshal(args, &a); err != nil {
		return nil, fmt.Errorf("parse args: %w", err)
	}
	if a.Path != "" && a.Content != "" {
		return nil, fmt.Errorf("path and content+source are mutually exclusive")
	}
	if a.Path == "" && a.Content == "" {
		return nil, fmt.Errorf("either path or content+source is required")
	}
	if s.pipeline.Complete == nil {
		return nil, fmt.Errorf("LLM not configured: set INGEST_LLM_URL")
	}

	if a.Path != "" {
		text, err := extract.Text(a.Path)
		if err != nil {
			return nil, fmt.Errorf("extract: %w", err)
		}
		source := a.Source
		if source == "" {
			source = filepath.Base(strings.TrimSuffix(a.Path, filepath.Ext(a.Path)))
		}
		return s.runIngest(ctx, text, source, a.DryRun)
	}
	if a.Source == "" {
		return nil, fmt.Errorf("source is required when content is provided")
	}
	return s.runIngest(ctx, a.Content, a.Source, a.DryRun)
}

type sessionLogArgs struct {
	SessionID   string `json:"session_id"`
	Skill       string `json:"skill,omitempty"`
	Phase       string `json:"phase,omitempty"`
	ProjectRoot string `json:"project_root,omitempty"`
	FinalStatus string `json:"final_status,omitempty"`
	FilePath    string `json:"file_path,omitempty"`
	ModelUsed   string `json:"model_used,omitempty"`
	DurationMs  int64  `json:"duration_ms,omitempty"`
	Message     string `json:"message,omitempty"`
}

func (s *Server) sessionLog(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
	var a sessionLogArgs
	if err := json.Unmarshal(args, &a); err != nil {
		return nil, fmt.Errorf("parse args: %w", err)
	}
	if a.SessionID == "" {
		return nil, fmt.Errorf("session_id is required")
	}
	entry := session.Entry{
		SessionID:   a.SessionID,
		Timestamp:   time.Now().UTC(),
		Skill:       a.Skill,
		Phase:       a.Phase,
		ProjectRoot: a.ProjectRoot,
		FinalStatus: a.FinalStatus,
		FilePath:    a.FilePath,
		ModelUsed:   a.ModelUsed,
		DurationMs:  a.DurationMs,
		Message:     a.Message,
	}
	dir := filepath.Join(s.brainDir, "sessions")
	if err := session.Append(dir, a.SessionID, entry); err != nil {
		return nil, fmt.Errorf("append: %w", err)
	}
	return json.Marshal(map[string]string{"status": "ok", "session_id": a.SessionID})
}

func (s *Server) runIngest(ctx context.Context, content, source string, dryRun bool) (json.RawMessage, error) {
	result, err := pipeline.Run(ctx, s.pipeline, s.brainDir, content, source, dryRun)
	if err != nil {
		return nil, fmt.Errorf("ingest: %w", err)
	}
	pages := result.Pages
	if pages == nil {
		pages = []string{}
	}
	warnings := result.Warnings
	if warnings == nil {
		warnings = []string{}
	}
	return json.Marshal(map[string]any{"pages": pages, "warnings": warnings})
}