The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
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"}
}