Add Beacon Agent Manifest for AI agent discovery#186
Add Beacon Agent Manifest for AI agent discovery#186enrichgateagent-png wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughAdds a Beacon Verified badge to the README and introduces a ChangesBeacon verification
Estimated code review effort: 1 (Trivial) | ~3 minutes Suggested labels: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Warning |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@beacon.json`:
- Around line 7-9: Update the interfaces entries in beacon.json so endpoints
contain callable interface URLs only: remove the mcp entry pointing to the
GitHub repository unless a public HTTP MCP endpoint is available, and replace or
remove the python entry because “pip install mcp-nixos” is installation guidance
rather than an endpoint. Preserve the repository URL in the existing source or
homepage fields.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 4e1af12b-9436-4dc5-8c68-4ce413cfd89d
📒 Files selected for processing (2)
README.mdbeacon.json
| "interfaces": [ | ||
| { "type": "python", "endpoint": "pip install mcp-nixos" }, | ||
| { "type": "mcp", "endpoint": "https://github.com/utensils/mcp-nixos" } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== files ==\n'
git ls-files | sed -n '1,200p'
printf '\n== beacon.json ==\n'
cat -n beacon.json
printf '\n== README candidates ==\n'
fd -a -e md -e markdown -g 'README*' .
printf '\n== search interfaces/beacon ==\n'
rg -n '"interfaces"|mcp-nixos|/mcp|beacon' -S . --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**'Repository: utensils/mcp-nixos
Length of output: 33455
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Narrow to any schema/docs if present.
fd -a -e json -e yaml -e yml -e md -e markdown -g '*beacon*' -g '*schema*' -g '*README*' .Repository: utensils/mcp-nixos
Length of output: 297
🌐 Web query:
"utensils mcp-nixos public MCP endpoint beacon.json interface endpoint"
💡 Result:
Based on your request, there are two distinct technologies involved that are often discussed in the context of Model Context Protocol (MCP) endpoints, but they serve different purposes: 1. MCP-NixOS (utensils/mcp-nixos): This is a server that provides AI assistants with access to NixOS data [1][2]. It does not natively use a beacon.json interface. Instead, when configured for remote access, it uses an MCP endpoint that defaults to /mcp [3][4]. Public instances of mcp-nixos exist, such as the one hosted at https://mcp-nixos.ncaq.net/mcp/ [5]. 2. Beacon (Scottcjn/beacon-skill): This is a separate social protocol for AI agents that explicitly utilizes a beacon.json file [6][7]. Agents in the Beacon ecosystem publish a signed JSON "agent card" at the.well-known/beacon.json endpoint for internet-scale discovery [6][8]. While Beacon can expose its tools to MCP-capable clients (such as Claude Code) via an MCP interface, the beacon.json file itself is a component of the Beacon protocol for agent discovery, not a standard part of the MCP-NixOS implementation [6][9]. In summary, beacon.json is an agent discovery card for the Beacon protocol [6][7], whereas mcp-nixos is an MCP server that typically uses a path-based HTTP endpoint (e.g., /mcp) for communication [3][4].
Citations:
- 1: https://utensils.io/mcp-nixos
- 2: https://github.com/utensils/mcp-nixos
- 3: https://github.com/utensils/mcp-nixos?tab=readme-ov-file
- 4: https://github.com/utensils/mcp-nixos/blob/main/README.md
- 5: Hosting mcp-nixos as a public MCP endpoint at https://mcp-nixos.ncaq.net/mcp/ #103
- 6: https://github.com/Scottcjn/beacon-skill
- 7: https://dev.to/scottcjn/introducing-beacon-why-ai-agents-need-a-social-protocol-1je0
- 8: https://github.com/Scottcjn/beacon-skill/blob/main/docs/AGENT_CARD.md
- 9: https://github.com/Scottcjn/beacon-skill/blob/main/README.md
🌐 Web query:
"Beacon manifest 0.1 interfaces python endpoint mcp endpoint schema"
💡 Result:
There is no single, industry-standard technology or specification referred to as "Beacon manifest 0.1" that integrates Python, MCP (Model Context Protocol), and a specific endpoint schema [1][2][3]. The term "Beacon" is used across multiple, unrelated technical domains [1][4][2][3]. To identify the specific system you are working with, you may be encountering one of the following: 1. Agentic Systems and MCP: In the context of the Model Context Protocol (MCP), a "manifest" often refers to a configuration file (like server.json) used for discovering tools, resources, and prompts [5][6]. Some systems use.well-known endpoints (e.g., /.well-known/mcp.json) to expose these manifests [6][7]. If your project involves Python-based MCP servers (e.g., using the official MCP Python SDK), the "manifest" is likely the JSON representation of the server capabilities exposed at the MCP connection point [5]. 2. Analytics SDKs: Several platforms (such as SoftAgility's Beacon) use the term "event manifest" [8][9][10]. These SDKs provide methods like exportEventManifest in Python, JavaScript, or C++ to generate a JSON file that defines event categories and names for a server-side allowlist [8][9][10]. 3. Platform Integration: Projects like inthevortex/Beacon use the term "Beacon SDK" to define interfaces for game platform plugins but do not typically use the specific "manifest 0.1" terminology in conjunction with MCP endpoints [1][11]. If you are developing an MCP server in Python, the protocol is standardized by the Model Context Protocol (MCP) spec, and you should refer to the official MCP documentation rather than a "Beacon" manifest. If you are referencing a specific proprietary framework, verify if it uses a.well-known endpoint or a specific registry (such as registry.modelcontextprotocol.io) [5].
Citations:
- 1: https://github.com/inthevortex/Beacon
- 2: https://docs.genomebeacons.org/framework/
- 3: https://ethereum.github.io/beacon-APIs/
- 4: https://developers.line.biz/en/docs/messaging-api/beacon-device-spec/
- 5: https://claudemarketplaces.com/mcp/io.github.tlennon-ie/neurodock-mcp-cognitive-graph
- 6: https://www.slickrock.dev/answers/mcp-integration-enterprise
- 7: https://www.slickrock.dev/answers/a2a-protocol-machine-discovery
- 8: https://github.com/SoftAgility/beacon-sdk-js/blob/main/CHANGELOG.md
- 9: https://docs.softagility.com/beacon/developers/sdk/cpp
- 10: https://docs.softagility.com/beacon/developers/sdk/dotnet/
- 11: https://github.com/inthevortex/Beacon/blob/ultimate/README.md
🌐 Web query:
"site:github.com/Scottcjn/beacon-skill beacon.json interfaces python endpoint install mcp endpoint"
💡 Result:
The beacon-skill project by Scottcjn is an agent communication framework that utilizes specific endpoints and configuration standards for discovery and message exchange [1][2][3]. ### Installation You can install the package via pip or npm: * Python (pip): pip install beacon-skill (optional: pip install "beacon-skill[mnemonic]" for BIP39 support, pip install "beacon-skill[dashboard]" for TUI) [1][3]. * npm (wrapper): npm install -g beacon-skill (installs a Python venv under the hood) [1][3]. ### Agent Discovery (beacon.json) Agents use a signed JSON card located at /.well-known/beacon.json for internet-scale discovery [1][4][3]. This file contains the agent ID, public key, transports (such as webhook and UDP), and capabilities [3]. * Generation: You can generate this card using the command beacon agent-card generate --name <agent_name> [3]. * Verification: The card is signed; verification is performed via the framework's internal logic (beacon_skill.agent_card.verify_agent_card) or the CLI command beacon agent-card verify <url> [4][3]. ### Endpoints The framework defines several standard HTTP endpoints for agent interaction [1][3]: * GET /.well-known/beacon.json: Used for agent discovery/agent cards [1][3]. * POST /beacon/inbox: Used to receive signed envelopes [1][3]. * GET /beacon/health: A health check endpoint that returns the agent ID [1][3]. ### MCP Support The framework includes support for the Model Context Protocol (MCP) [1][2]. By running beacon mcp, you can expose Beacon tools—including send, inbox, discover, and identity—to any MCP-capable client, such as Claude Code [1][5].
Citations:
- 1: https://github.com/Scottcjn/beacon-skill/blob/main/README.md
- 2: https://github.com/Scottcjn/beacon-skill
- 3: https://github.com/Scottcjn/beacon-skill/tree/v2.8.0
- 4: https://github.com/Scottcjn/beacon-skill/blob/main/docs/AGENT_CARD.md
- 5: docs: add webhook communication example to quickstart.py Scottcjn/beacon-skill#880
🌐 Web query:
"beacon.json interfaces type python endpoint pip install schema"
💡 Result:
The beacon.json file is a standardized agent card used within the Beacon framework for internet-scale agent discovery. It is typically served at the path /.well-known/beacon.json by Beacon-compatible agents [1][2]. Key components of the beacon.json interface and schema include: - Purpose: It allows other agents to discover an agent's stable agent_id, verify its public key, and identify supported communication transports [1]. - Core Schema: The JSON structure requires fields such as beacon_version, agent_id, public_key_hex, and a signature [1][2]. It also includes optional fields for transports (e.g., udp, webhook), capabilities (e.g., payments, kinds), and a human-readable name [1][2]. - Verification: The signature is generated by signing the agent card (excluding the signature field itself) using the agent's private key. Clients verify this using the public_key_hex [1]. To work with Beacon, you can use the beacon-skill Python package, which provides CLI tools for generating and verifying these agent cards [3][2]. Installation: You can install the package via pip: pip install beacon-skill Usage Examples: - Generate an agent card: beacon agent-card generate --name your-agent-name - Verify a remote agent's card: beacon agent-card verify https://agent.example.com/.well-known/beacon.json Beacon-enabled agents also typically expose other endpoints, such as GET /beacon/health and POST /beacon/inbox, to facilitate network interactions [2][4].
Citations:
- 1: https://github.com/Scottcjn/beacon-skill/blob/main/docs/AGENT_CARD.md
- 2: https://pypi.org/project/beacon-skill/2.15.1/
- 3: https://pypi.org/project/beacon-skill/
- 4: https://github.com/Scottcjn/beacon-skill/blob/main/README.md
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== README HTTP/install sections ==\n'
sed -n '1,140p' README.md | nl -ba | sed -n '55,120p'
printf '\n== README install/package sections ==\n'
sed -n '250,330p' README.md | nl -ba | sed -n '1,120p'
printf '\n== .mcp.json ==\n'
cat -n .mcp.jsonRepository: utensils/mcp-nixos
Length of output: 232
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== README 1-140 ==\n'
sed -n '1,140p' README.md | cat -n
printf '\n== README 260-320 ==\n'
sed -n '260,320p' README.md | cat -n
printf '\n== .mcp.json ==\n'
cat -n .mcp.json
printf '\n== beacon-related docs refs ==\n'
rg -n 'beacon\.json|Beacon Verified|interfaces|mcp endpoint|/mcp|pip install mcp-nixos|pip install beacon-skill' README.md website CLAUDE.md RELEASE_NOTES.md beacon.json .mcp.jsonRepository: utensils/mcp-nixos
Length of output: 19292
interfaces[1].endpoint should not point at GitHub
source/homepage already cover the repository URL. The mcp interface needs a callable MCP URL; if there isn’t a public HTTP endpoint yet, drop this entry until one exists. The pip install mcp-nixos value also reads like install guidance, not an interface endpoint.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@beacon.json` around lines 7 - 9, Update the interfaces entries in beacon.json
so endpoints contain callable interface URLs only: remove the mcp entry pointing
to the GitHub repository unless a public HTTP MCP endpoint is available, and
replace or remove the python entry because “pip install mcp-nixos” is
installation guidance rather than an endpoint. Preserve the repository URL in
the existing source or homepage fields.
1 participant
Beacon Agent Manifest (optional, ~2 min review)
Beacon is an open agent registry (33k+ MCP servers & agents). You are already indexed from GitHub.
This PR adds:
beacon.json— open v0.1 standard for machine-readable agent discovery (Claude, Cursor MCP, etc.)No API keys, no accounts. Hosting
beacon.jsonin your repo is the verification (location = proof).If merged, Beacon auto-upgrades your listing to verified manifest on the next scan.
Spec: https://github.com/enrichgateagent-png/beacon-agent-manifest · llms.txt
Summary by CodeRabbit