Files
ZacharyZhang-NY eb50367921
ci / backend (push) Failing after 3m25s
ci / mcp (push) Successful in 21s
ci / interface (push) Successful in 19s
ci / image (push) Failing after 1m5s
Move the canonical host to git.zacharyzhang.com and follow the module path
The GitHub account that hosted this repository is suspended, so the remote
is dead and the vanity import github.com/ZacharyZhang-NY/ely-eye/... no
longer resolves. The Go module path is that import, so it moves with the
host: git.zacharyzhang.com serves a go-import meta tag for the nested
ely-eye-mcp submodule, which go build and go get both need.

The installers read release assets from the host too, so their API and
download URLs move with it. The release workflow's -ldflags symbol path is
the module path, so it moves as well; a build stamped with the new path
prints the stamped version.
2026-10-10 11:26:19 -04:00

217 lines
6.8 KiB
Go

// Package apiclient talks to a running Ely-Eye API server. The Python service
// owns every write rule, so the MCP server forwards mutations instead of
// duplicating them against SQLite.
package apiclient
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strings"
"time"
"git.zacharyzhang.com/ZacharyZhang-NY/ely-eye/ely-eye-mcp/internal/domain"
)
const maxErrorBody = 4096
type Client struct {
BaseURL string
Token string
HTTP *http.Client
}
func New(baseURL string) *Client {
if strings.TrimSpace(baseURL) == "" {
baseURL = "http://127.0.0.1:8765"
}
return &Client{
BaseURL: strings.TrimRight(baseURL, "/"),
Token: strings.TrimSpace(os.Getenv("ELY_EYE_AUTH_TOKEN")),
HTTP: &http.Client{Timeout: 30 * time.Second},
}
}
// authorize attaches the write token; the server refuses a write without it.
func (c *Client) authorize(request *http.Request) {
if c.Token != "" {
request.Header.Set("Authorization", "Bearer "+c.Token)
}
}
// Get fetches a JSON resource into out.
func (c *Client) Get(ctx context.Context, path string, out any) error {
request, err := http.NewRequestWithContext(ctx, http.MethodGet, c.BaseURL+path, nil)
if err != nil {
return fmt.Errorf("cannot build the request for %s: %w", path, err)
}
c.authorize(request)
return c.do(request, path, out)
}
func (c *Client) do(request *http.Request, path string, out any) error {
response, err := c.HTTP.Do(request)
if err != nil {
return fmt.Errorf("the Ely-Eye API at %s is unreachable; start it with `ely-eye serve`: %w", c.BaseURL, err)
}
defer response.Body.Close()
data, err := io.ReadAll(io.LimitReader(response.Body, maxErrorBody))
if err != nil {
return fmt.Errorf("%s returned an unreadable body: %w", path, err)
}
if response.StatusCode < 200 || response.StatusCode >= 300 {
return errors.New(path + " was rejected: " + serverReason(response.StatusCode, data))
}
if out == nil {
return nil
}
if err := json.Unmarshal(data, out); err != nil {
return fmt.Errorf("%s returned JSON that does not decode: %w", path, err)
}
return nil
}
// Post sends body as JSON and decodes the response into out. A rejected request
// carries the server's own reason, which is the rule the caller broke.
func (c *Client) Post(ctx context.Context, path string, body any, out any) error {
payload, err := json.Marshal(body)
if err != nil {
return fmt.Errorf("cannot encode the request for %s: %w", path, err)
}
request, err := http.NewRequestWithContext(ctx, http.MethodPost, c.BaseURL+path, bytes.NewReader(payload))
if err != nil {
return fmt.Errorf("cannot build the request for %s: %w", path, err)
}
request.Header.Set("Content-Type", "application/json")
c.authorize(request)
return c.do(request, path, out)
}
// serverReason prefers FastAPI's {"detail": "..."} so the caller sees the broken
// rule instead of an HTML error page.
func serverReason(status int, data []byte) string {
var envelope struct {
Detail string `json:"detail"`
}
if err := json.Unmarshal(data, &envelope); err == nil && strings.TrimSpace(envelope.Detail) != "" {
return envelope.Detail
}
trimmed := strings.TrimSpace(string(data))
if trimmed == "" {
return fmt.Sprintf("HTTP %d with no reason", status)
}
return trimmed
}
// WorkingSet asks for what one session recorded, in the order it recorded it,
// with no ranking involved. The session is required: without one, every memory
// in the store would be working memory.
func (c *Client) WorkingSet(ctx context.Context, holder, session string) ([]domain.Memory, error) {
if strings.TrimSpace(holder) == "" {
return nil, errors.New("holder is required")
}
if strings.TrimSpace(session) == "" {
return nil, errors.New("session is required")
}
path := "/api/memory/working?holder=" + url.QueryEscape(holder) + "&session=" + url.QueryEscape(session)
var atoms []domain.Memory
if err := c.Get(ctx, path, &atoms); err != nil {
return nil, err
}
return atoms, nil
}
// Conflicts lists the disagreements the store noticed and nobody has settled.
// An empty holder asks for every holder's, which is what an operator reviewing
// the whole store wants.
func (c *Client) Conflicts(ctx context.Context, holder string) ([]domain.ConflictRecord, error) {
path := "/api/memory/conflicts"
if strings.TrimSpace(holder) != "" {
path += "?holder=" + url.QueryEscape(holder)
}
var records []domain.ConflictRecord
if err := c.Get(ctx, path, &records); err != nil {
return nil, err
}
return records, nil
}
// SearchOptions is one ranked query. Empty optional fields are omitted, so the
// server's own defaults decide rather than a zero value invented here.
type SearchOptions struct {
Query string
Modality string
Holder string
Scenario string
Limit int
}
// SearchResult carries the server's own verdict: "no_match" is a claim about the
// corpus, an empty hit list is not.
type SearchResult struct {
Status string `json:"status"`
Hits []domain.AtomHit `json:"hits"`
NextCursor string `json:"next_cursor"`
}
// Search asks the running server to rank. The ranking lives in one place, so an
// MCP hit cannot disagree with an HTTP or CLI hit for the same query.
func (c *Client) Search(ctx context.Context, options SearchOptions) (*SearchResult, error) {
if strings.TrimSpace(options.Query) == "" {
return nil, errors.New("query is required")
}
body := map[string]any{"query": options.Query}
if options.Limit > 0 {
body["top_k"] = options.Limit
}
filters := map[string]string{}
for key, value := range map[string]string{
"modality": options.Modality,
"holder": options.Holder,
"scenario": options.Scenario,
} {
if value != "" {
filters[key] = value
}
}
if len(filters) > 0 {
body["filters"] = filters
}
var result SearchResult
if err := c.Post(ctx, "/api/search", body, &result); err != nil {
return nil, err
}
return &result, nil
}
// Card asks what the store can answer: the schema its answers come out under, which
// senses its memory actually covers, and who is in the directory. It is served
// without a token, so a caller can decide whether to send questions at all.
func (c *Client) Card(ctx context.Context) (*domain.CapabilityCard, error) {
var card domain.CapabilityCard
if err := c.Get(ctx, "/api/card", &card); err != nil {
return nil, err
}
return &card, nil
}
// HolderCard asks the same question about one holder. The server derives it from the
// memories that holder owns, so a card cannot promise a modality the store lacks.
func (c *Client) HolderCard(ctx context.Context, holderID string) (*domain.HolderCard, error) {
if strings.TrimSpace(holderID) == "" {
return nil, errors.New("holder_id is required")
}
var card domain.HolderCard
if err := c.Get(ctx, "/api/card/"+url.PathEscape(holderID), &card); err != nil {
return nil, err
}
return &card, nil
}