Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

The agent example is undocumented

Open
  • Is something wrong?
#422 3 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@GazzyLee is already working on this.

Since Oct 17, 2026.

  • #452 by @sparkysolutions10-pixel — open
  • #486 by @GazzyLee — open

Assessment

This issue has not been assessed yet.

Description

area:docs difficulty:easy help wanted points:100 Stellar Wave
Background

package.json exposes two commands:

"mcp:server": "tsx examples/mcp-server/run.ts",
"mcp:agent": "tsx examples/mcp-server/agent.ts"

Neither is explained anywhere a reader would look. There is no README in
examples/mcp-server/, nothing in the repo README, and no description of what
the agent example does, what it needs, or what it will spend.

Someone who runs npm run mcp:server without reading the source will discover
its requirements through a startup failure, and its behaviour by watching it.
For a tool that signs with a mainnet key, that is the wrong order.

What to build
  • A README in examples/mcp-server/ covering what each command does, what
    configuration it needs, which network it talks to, and what it can spend.
  • A worked example of connecting a client and calling each tool.
  • A prominent warning about the mainnet key, with the safe way to try it first.
  • A link from the repo README, next to the REST and GraphQL documentation.
  • Every example runnable exactly as written.
Acceptance criteria
  • examples/mcp-server/README.md exists and is linked from the repo README
  • Both npm commands are documented with their configuration
  • The spending risk is stated prominently
  • A client connection example is included and works as written
  • No key, address or contract id in any example is shortened

Drips Wave · Complexity: Easy · 100 points

Repo: Divinity-Labs/Lens. The MCP server is src/mcp/server.ts
(BazaarMcpServer) with error codes in src/mcp/codes.ts. It is started by
npm run mcp:server → examples/mcp-server/run.ts, and there is an agent
example at examples/mcp-server/agent.ts. Tests are tests/mcp.test.ts.

Run the tests: npm test. The tests are vitest, not jest. A single file
is npx vitest run tests/mcp.test.ts.

Load test (prices) is already failing on main. Not your PR.

This surface signs with a real mainnet key. examples/mcp-server/run.ts
requires MCP_AGENT_SECRET_KEY_MAINNET and builds a signer for
stellar:pubnet. Anything you change here can move real money, so prefer
failing closed, and never log, echo or test with a real secret key.

Never elide an address, a contract id or a key in code, comments or
fixtures. A previous batch shortened a contract id and five contributors
invented plausible-looking ids to fill the gap. Write it in full or not at all.

An agent is the least able caller to notice a wrong answer. It will reason
over whatever it is handed, confidently. Prefer a structured error over a
best-effort result.

Required: Before submitting, join the contributor Telegram so your work can be tracked and counted toward the Stellar Wave: https://t.me/+fxHXq8f1SwlkZDBk

Dominant language
TypeScript
Stars
4
Forks
71
Avg merge
1d 9h
Merged PRs (30d)
34

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Divinity-Labs/Lens

All issues in Divinity-Labs/Lens

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.