Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

11.5 KB
Raw Blame
package mcpserver

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

	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/agentskills"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/intel"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/launchpkg"
	"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
	"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve/intelapi"
)

// Beacon Intel tools: check an MCP server or skill against the free public index at
// intel.beacon.sh before installing or running it. These are the local server's only tools
// that reach the network, and only when an agent calls one; each sends just what it names
// (intel_check_installed: the public identifiers internal/intel derives from inventory).

// intelInstalledMatches is how many matches intel_check_installed keeps per artifact.
const intelInstalledMatches = 3

func defaultIntelClient() (*intelapi.Client, error) {
	return intel.New("beacon-mcp/" + version.GetVersion() + " (+https://beacon.sh)")
}

// defaultInventory scans what the agent asking has configured. The agent starts every launcher
// with this process's environment and in its project, so their registry settings apply too.
func defaultInventory(includeProject bool) inventory.Result {
	env := launchpkg.CurrentRegistryEnv()
	opts := inventory.Options{SkipProjectScope: !includeProject, LauncherEnv: &env}
	if includeProject {
		if wd, err := os.Getwd(); err == nil {
			opts.WorkingDir = wd
		}
	}
	return inventory.Scan(opts)
}

func (s *Server) intelClient() (*intelapi.Client, error) {
	if s.newIntel != nil {
		return s.newIntel()
	}
	return defaultIntelClient()
}

// intelToolNames is what this server calls the tools intelapi defines for every Beacon server;
// Beacon Cloud MCP names the same tools beacon_intel_*.
var intelToolNames = intelapi.ToolNames{Lookup: "intel_lookup", GetArtifact: "intel_get_artifact", Check: "intel_check"}

func (s *Server) registerIntelTools() {
	// Each tool parses its arguments into the one request it makes. Arguments are checked before
	// the client is made, so a bad call says what is wrong with it even when BEACON_INTEL=0.
	type request func(context.Context, *intelapi.Client) ([]byte, error)
	parse := map[string]func(intelapi.Args) (request, error){
		intelToolNames.Lookup: func(a intelapi.Args) (request, error) {
			req, err := intelapi.ParseLookupArgs(a)
			return func(ctx context.Context, c *intelapi.Client) ([]byte, error) {
				_, raw, err := c.Lookup(ctx, req.Q, req.Kind, req.Limit)
				return raw, err
			}, err
		},
		intelToolNames.GetArtifact: func(a intelapi.Args) (request, error) {
			key, err := intelapi.ParseArtifactArgs(a)
			return func(ctx context.Context, c *intelapi.Client) ([]byte, error) {
				_, raw, err := c.Artifact(ctx, key)
				if intelapi.NotFound(err) {
					return nil, fmt.Errorf("no artifact in Beacon Intel has that key; find one with %s", intelToolNames.Lookup)
				}
				return raw, err
			}, err
		},
		intelToolNames.Check: func(a intelapi.Args) (request, error) {
			items, err := intelapi.ParseCheckArgs(a)
			return func(ctx context.Context, c *intelapi.Client) ([]byte, error) {
				_, raw, err := c.Check(ctx, items)
				return raw, err
			}, err
		},
	}
	for _, spec := range intelapi.Tools(intelToolNames) {
		parseArgs := parse[spec.Name]
		schema := objectSchema(spec.Properties, spec.Required)
		schema["additionalProperties"] = false
		s.register(Tool{
			Name:        spec.Name,
			Description: spec.Description,
			InputSchema: schema,
			handler: func(ctx context.Context, args map[string]interface{}) (interface{}, error) {
				a, err := intelapi.ArgsFromMap(args)
				if err != nil {
					return nil, err
				}
				send, err := parseArgs(a)
				if err != nil {
					return nil, err
				}
				client, err := s.intelClient()
				if err != nil {
					return nil, err
				}
				raw, err := send(ctx, client)
				if err != nil {
					return nil, err
				}
				return json.RawMessage(raw), nil
			},
		})
	}
	s.register(Tool{
		Name: "intel_check_installed",
		Description: "Check the MCP servers and skills configured on this machine against Beacon Intel, the way a dependency audit checks a lockfile. " +
			"Beacon reads each runtime's own config (Claude Code, Cursor, Codex, and the rest Beacon supports) and by default sends only identifiers it can read exactly: npm and PyPI packages, from the public registries, named in a server's launch command, and the skill:<owner>/<repo>#<name> key of a skill the skills CLI installed from GitHub. " +
			"Names that may be private (a server's configured name, a package from a private registry or index, the name of any other skill) are listed as skipped unless the user agrees to include_private_names. " +
			"Paths, URLs, environment and other arguments never leave the machine. " +
			fmt.Sprintf("Use dry_run to see exactly what would be sent without sending it. Read a concerning result in full with %s.", intelToolNames.GetArtifact),
		InputSchema: checkInstalledSchema(),
		handler:     s.checkInstalled,
	})
}

func checkInstalledSchema() map[string]interface{} {
	schema := objectSchema(map[string]interface{}{
		"include_private_names": map[string]interface{}{"type": "boolean", "description": "Also send names that may be private: servers' configured names, packages from a private registry or index, and the names of skills with no GitHub source. Off by default; set it only when the user agrees."},
		"include_project":       map[string]interface{}{"type": "boolean", "description": "Also read project-scoped config in the server's working directory (default true)."},
		"dry_run":               map[string]interface{}{"type": "boolean", "description": "List what would be sent, and send nothing."},
	}, nil)
	schema["additionalProperties"] = false
	return schema
}

type checkInstalledArgs struct {
	includePrivateNames, includeProject, dryRun bool
}

// parseCheckInstalledArgs refuses an argument the tool does not take and a value that is not a
// JSON bool, rather than falling back to a default: {"dry_run": "true"} must never become a
// live send.
func parseCheckInstalledArgs(args map[string]interface{}) (checkInstalledArgs, error) {
	out := checkInstalledArgs{includeProject: true}
	for key, raw := range args {
		var dst *bool
		switch key {
		case "include_private_names":
			dst = &out.includePrivateNames
		case "include_project":
			dst = &out.includeProject
		case "dry_run":
			dst = &out.dryRun
		default:
			return out, fmt.Errorf("intel_check_installed does not take %q", key)
		}
		value, ok := raw.(bool)
		if !ok {
			return out, fmt.Errorf("%s must be true or false", key)
		}
		*dst = value
	}
	return out, nil
}

type installedResult struct {
	Kind     string                  `json:"kind"`
	Q        string                  `json:"q"`
	Basis    string                  `json:"basis"`
	FoundIn  []intel.InstalledSource `json:"found_in"`
	Status   string                  `json:"status"`
	Risk     string                  `json:"risk,omitempty"`
	Guidance string                  `json:"guidance,omitempty"`
	// NameOnly marks a match made on a name alone: it may be a different artifact that
	// happens to share the name, so its risk is a lead to confirm, not a verdict on this one.
	NameOnly bool               `json:"name_only,omitempty"`
	Matches  []intelapi.Summary `json:"matches,omitempty"`
}

const nameOnlyGuidance = "Matched by name only: confirm the installed one comes from the matched repository before relying on this. "

type installedReport struct {
	DryRun  bool                 `json:"dry_run,omitempty"`
	Sent    []intelapi.CheckItem `json:"sent"`
	Results []installedResult    `json:"results,omitempty"`
	Counts  map[string]int       `json:"counts,omitempty"`
	Skipped []intel.Skipped      `json:"skipped"`
	Note    string               `json:"note"`
}

func (s *Server) checkInstalled(ctx context.Context, args map[string]interface{}) (interface{}, error) {
	a, err := parseCheckInstalledArgs(args)
	if err != nil {
		return nil, err
	}
	var inv inventory.Result
	if s.inventory != nil {
		inv = s.inventory(a.includeProject)
	} else {
		inv = defaultInventory(a.includeProject)
	}
	items, skipped := intel.FromInventory(inv, intel.FromInventoryOptions{
		IncludePrivateNames: a.includePrivateNames,
		BeaconSkill:         beaconSkill(agentskills.Names()),
	})
	report := installedReport{Sent: make([]intelapi.CheckItem, len(items)), Skipped: skipped}
	if report.Skipped == nil {
		report.Skipped = []intel.Skipped{}
	}
	for i, item := range items {
		report.Sent[i] = intelapi.CheckItem{Q: item.Q, Kind: item.Kind}
	}
	if a.dryRun {
		report.DryRun = true
		report.Note = "Nothing was sent. These lookups would go to Beacon Intel; skipped entries would not."
		return report, nil
	}
	if len(items) == 0 {
		report.Note = "No MCP server or skill on this machine has a public identifier to check; see skipped."
		return report, nil
	}
	client, err := s.intelClient()
	if err != nil {
		return nil, err
	}
	report.Counts = map[string]int{}
	for start := 0; start < len(items); start += intelapi.MaxCheck {
		end := min(start+intelapi.MaxCheck, len(items))
		res, _, err := client.Check(ctx, report.Sent[start:end])
		if err != nil {
			return nil, err
		}
		if len(res.Results) != end-start {
			return nil, fmt.Errorf("Beacon Intel answered %d results for %d artifacts", len(res.Results), end-start)
		}
		for i, outcome := range res.Results {
			item := items[start+i]
			matches := outcome.Matches
			if len(matches) > intelInstalledMatches {
				matches = matches[:intelInstalledMatches]
			}
			result := installedResult{
				Kind: item.Kind, Q: item.Q, Basis: item.Basis, FoundIn: item.Sources,
				Status: outcome.Status, Risk: outcome.Risk, Guidance: outcome.Guidance, Matches: matches,
			}
			// A name, or a package or repository the index fell back to matching as a name, may
			// be a different artifact that shares it.
			// A package from a private registry or index is matched against the public package
			// that shares its name, which may be a different artifact too.
			byName := item.Basis == intel.BasisSkillName || item.Basis == intel.BasisServerName ||
				intel.IsPrivateBasis(item.Basis) || outcome.MatchedBy == "text"
			if outcome.Status == "matched" && byName {
				result.NameOnly = true
				result.Guidance = nameOnlyGuidance + result.Guidance
			}
			report.Results = append(report.Results, result)
			key := outcome.Status
			if outcome.Status == "matched" && outcome.Risk != "" {
				key = outcome.Risk
			}
			report.Counts[key]++
		}
	}
	report.Note = "not_found means never checked, not safe. ambiguous claims no risk: check a candidate with intel_get_artifact. " + intelapi.UntrustedNote
	return report, nil
}

// beaconSkill reports whether an inventoried skill is one Beacon installed: one of its skill
// names, in a user-level directory carrying Beacon's marker. Beacon never installs project
// skills, so a repository's own skill directories are never taken for Beacon's or read for it.
func beaconSkill(names []string) func(inventory.Skill) bool {
	known := map[string]bool{}
	for _, name := range names {
		known[name] = true
	}
	return func(s inventory.Skill) bool {
		return known[strings.TrimSpace(s.SkillName)] && s.SourceScope == inventory.ScopeUser && s.ManifestPath != "" && agentskills.Managed(filepath.Dir(s.ManifestPath))
	}
}

// intelTools lists the Beacon Intel tools, for doctor and tests.
func intelTools() []string {
	return []string{intelToolNames.Lookup, intelToolNames.GetArtifact, intelToolNames.Check, "intel_check_installed"}
}