mcp.go

// Package client implements an MCP JSON-RPC client for Pipeboard servers.
package client

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"sync/atomic"
)

// Client talks to Pipeboard MCP servers over HTTP.
type Client struct {
	baseURL    string
	token      string
	version    string
	userAgent  string
	httpClient *http.Client
	reqID      atomic.Int64
}

// New creates an MCP client. version is used in the User-Agent header
// and the MCP clientInfo.
func New(baseURL, token, version string) *Client {
	return &Client{
		baseURL:    baseURL,
		token:      token,
		version:    version,
		userAgent:  "pipeboard-cli/" + version,
		httpClient: &http.Client{},
	}
}

// jsonRPCRequest is a JSON-RPC 2.0 request.
type jsonRPCRequest struct {
	JSONRPC string      `json:"jsonrpc"`
	ID      int64       `json:"id"`
	Method  string      `json:"method"`
	Params  interface{} `json:"params,omitempty"`
}

// jsonRPCResponse is a JSON-RPC 2.0 response.
type jsonRPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int64           `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *jsonRPCError   `json:"error,omitempty"`
}

type jsonRPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

func (e *jsonRPCError) Error() string {
	return fmt.Sprintf("MCP error %d: %s", e.Code, e.Message)
}

// ToolAnnotations carries the MCP tool behavior hints (spec 2025-06-18 / 2025-11-25).
// All fields are HINTS that clients use for UX (confirmation prompts, grouping)
// not enforcement. Spec defaults when unset: readOnlyHint=false,
// destructiveHint=true, idempotentHint=false, openWorldHint=true.
type ToolAnnotations struct {
	Title           string `json:"title,omitempty"`
	ReadOnlyHint    *bool  `json:"readOnlyHint,omitempty"`
	DestructiveHint *bool  `json:"destructiveHint,omitempty"`
	IdempotentHint  *bool  `json:"idempotentHint,omitempty"`
	OpenWorldHint   *bool  `json:"openWorldHint,omitempty"`
}

// ToolDefinition represents a tool from tools/list.
//
// Title is the tool's human-readable display name. Note there are TWO places a
// title can live: this top-level field (MCP spec 2025-06-18 onward, what
// Pipeboard servers populate) and the legacy `annotations.title`. Without the
// top-level field here, every tool decoded as untitled — including in `--json`
// output and the on-disk tools cache, both of which re-marshal this struct — so
// `tools-list` reported 0/63 titled against a server that returns 63/63.
type ToolDefinition struct {
	Name        string           `json:"name"`
	Title       string           `json:"title,omitempty"`
	Description string           `json:"description"`
	InputSchema json.RawMessage  `json:"inputSchema"`
	Annotations *ToolAnnotations `json:"annotations,omitempty"`
}

// DisplayTitle returns the tool's human-readable title, preferring the
// top-level field and falling back to the legacy `annotations.title`. Empty
// when the server sends neither — which for a Pipeboard server means a real
// compliance gap (a title is a blocking Claude Connectors submission
// requirement), so callers should show its absence rather than paper over it
// with the machine name.
func (t ToolDefinition) DisplayTitle() string {
	if t.Title != "" {
		return t.Title
	}
	if t.Annotations != nil {
		return t.Annotations.Title
	}
	return ""
}

// ToolsListResult is the result of tools/list.
type ToolsListResult struct {
	Tools []ToolDefinition `json:"tools"`
}

// Initialize performs the MCP handshake with a server.
func (c *Client) Initialize(serverPath string) error {
	params := map[string]interface{}{
		"protocolVersion": "2025-03-26",
		"capabilities":    map[string]interface{}{},
		"clientInfo": map[string]string{
			"name":    "pipeboard-cli",
			"version": c.version,
		},
	}

	_, err := c.call(serverPath, "initialize", params)
	if err != nil {
		return fmt.Errorf("initialize: %w", err)
	}

	// Send initialized notification (no response expected)
	_ = c.notify(serverPath, "notifications/initialized", nil)

	return nil
}

// ListTools fetches the list of tools from an MCP server.
func (c *Client) ListTools(serverPath string) (*ToolsListResult, error) {
	raw, err := c.call(serverPath, "tools/list", nil)
	if err != nil {
		return nil, fmt.Errorf("tools/list: %w", err)
	}

	var result ToolsListResult
	if err := json.Unmarshal(raw, &result); err != nil {
		return nil, fmt.Errorf("parsing tools/list result: %w", err)
	}
	return &result, nil
}

// CallTool invokes a tool on an MCP server and returns the raw result.
func (c *Client) CallTool(serverPath, toolName string, arguments map[string]interface{}) (json.RawMessage, error) {
	params := map[string]interface{}{
		"name":      toolName,
		"arguments": arguments,
	}

	raw, err := c.call(serverPath, "tools/call", params)
	if err != nil {
		return nil, fmt.Errorf("tools/call %s: %w", toolName, err)
	}
	return raw, nil
}

func (c *Client) call(serverPath, method string, params interface{}) (json.RawMessage, error) {
	id := c.reqID.Add(1)

	req := jsonRPCRequest{
		JSONRPC: "2.0",
		ID:      id,
		Method:  method,
		Params:  params,
	}

	body, err := json.Marshal(req)
	if err != nil {
		return nil, fmt.Errorf("marshaling request: %w", err)
	}

	url := fmt.Sprintf("%s/%s", c.baseURL, serverPath)
	httpReq, err := http.NewRequest("POST", url, bytes.NewReader(body))
	if err != nil {
		return nil, fmt.Errorf("creating request: %w", err)
	}

	httpReq.Header.Set("Content-Type", "application/json")
	setCommonHeaders(httpReq, c.token, c.userAgent)

	resp, err := c.httpClient.Do(httpReq)
	if err != nil {
		return nil, fmt.Errorf("sending request: %w", err)
	}
	defer resp.Body.Close()

	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("reading response: %w", err)
	}

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(respBody))
	}

	var rpcResp jsonRPCResponse
	if err := json.Unmarshal(respBody, &rpcResp); err != nil {
		return nil, fmt.Errorf("parsing response: %w", err)
	}

	if rpcResp.Error != nil {
		return nil, rpcResp.Error
	}

	return rpcResp.Result, nil
}

// ToolsHashResult is the response from GET /tools-hash.
type ToolsHashResult struct {
	Hash string `json:"hash"`
}

// FetchToolsHash retrieves the combined tools hash from the server.
// baseURL is the MCP base URL (e.g. https://mcp.pipeboard.co).
// This endpoint requires no authentication, but it still needs the Vercel
// protection bypass when baseURL is a preview deployment.
func FetchToolsHash(baseURL, version string) (*ToolsHashResult, error) {
	req, err := http.NewRequest("GET", baseURL+"/api/tools-hash", nil)
	if err != nil {
		return nil, fmt.Errorf("creating request: %w", err)
	}
	setCommonHeaders(req, "", "pipeboard-cli/"+version)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("fetching tools hash: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("tools-hash HTTP %d", resp.StatusCode)
	}

	var result ToolsHashResult
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return nil, fmt.Errorf("parsing tools-hash: %w", err)
	}
	return &result, nil
}

func (c *Client) notify(serverPath, method string, params interface{}) error {
	// Notifications have no ID and expect no response.
	type notification struct {
		JSONRPC string      `json:"jsonrpc"`
		Method  string      `json:"method"`
		Params  interface{} `json:"params,omitempty"`
	}

	req := notification{
		JSONRPC: "2.0",
		Method:  method,
		Params:  params,
	}

	body, err := json.Marshal(req)
	if err != nil {
		return err
	}

	url := fmt.Sprintf("%s/%s", c.baseURL, serverPath)
	httpReq, err := http.NewRequest("POST", url, bytes.NewReader(body))
	if err != nil {
		return err
	}

	httpReq.Header.Set("Content-Type", "application/json")
	setCommonHeaders(httpReq, c.token, c.userAgent)

	resp, err := c.httpClient.Do(httpReq)
	if err != nil {
		return err
	}
	resp.Body.Close()
	return nil
}