A pnpm monorepo of Sphere DM bots — Node.js services that own a Sphere blockchain wallet, listen for Nostr DMs (or post to NIP-29 group chats), and respond using an LLM plus tools exposed over the Model Context Protocol (MCP).

kbbot and viktor share the @agentic/sphere-bot library (agent loop, MCP tool manager, model factory). chess-bot and unicity-l3 use the Sphere SDK directly.

   ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌────────────┐
   │   kbbot   │ │  viktor   │ │ chess-bot │ │ unicity-l3 │
   │ (DM bot)  │ │ (DM bot)  │ │ (group)   │ │ (group)    │
   └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬──────┘
         │             │             │             │
         │  Sphere SDK │ Sphere SDK  │ Sphere SDK  │ Sphere SDK
         │  (Nostr DM, NIP-17, NIP-29 group chat)  │
         ▼             ▼             ▼             ▼
   ┌─────────────────────────────────────────────────────┐
   │              Nostr relays (testnet/mainnet)         │
   └─────────────────────────────────────────────────────┘

         ┌─────────┐         ┌─────────┐
   MCP   │ mcp-rag │         │ mcp-web │ ──HTTP──► searxng
  ─────► │ (Python)│         │(Python) │           (search)
         │ Chroma  │         │ search+ │
         │  /rag   │         │  fetch  │
         └─────────┘         └─────────┘
                  ▲              ▲
                  └──── kbbot, viktor (MCP/HTTP)

• Node.js 20+
• pnpm 8+
• Docker & Docker Compose
• Python 3.10+ (only if running the MCP servers outside Docker)

git clone <repository>
cd agentic-chatbot
pnpm install
cp .env.example .env          # fill in API keys + bot mnemonics
docker compose up --build

pnpm --filter kbbot dev
pnpm --filter viktor dev
pnpm --filter chess-bot dev
pnpm --filter unicity-l3 dev

cd packages/mcp-rag && python -m venv venv && source venv/bin/activate \
  && pip install -e . && python -m src.server

cd packages/mcp-web-py && python -m venv venv && source venv/bin/activate \
  && pip install -e . && python -m src.server

Each bot owns a Sphere wallet persisted under data/<bot>/data/wallet.json (bind-mounted into the container). On startup the bot calls Sphere.init({ autoGenerate: false, mnemonic: ... }):

• If wallet.json exists — it's loaded and the env var is ignored.
• If wallet.json is missing — the matching *_MNEMONIC env var must be set, otherwise the SDK throws "No wallet exists and no mnemonic provided" and the bot refuses to start.

The mnemonic env vars are:

autoGenerate is intentionally off so a corrupt wallet.json cannot silently cause an identity swap on restart. To bootstrap a fresh deployment, set the corresponding *_MNEMONIC once; you can leave it set afterwards as a recovery fallback or remove it.

data/
├── kbbot/{data,tokens}/
├── viktor/{data,tokens}/
├── chess-bot/{data,tokens}/
├── unicity-l3/{data,tokens}/
├── mcp-rag/chromadb/
└── searxng/

The data/ directory is gitignored. Use the backup script to migrate:

./scripts/bot-backup.sh backup kbbot          # creates kbbot-backup.tar.gz
./scripts/bot-backup.sh restore kbbot         # extracts into data/kbbot/

Same for viktor, chess-bot, unicity-l3.

See .env.example for the full list. Highlights:

The @agentic/sphere-bot library is configured per-bot via packages/<bot>/src/config.ts. Key fields:

• llm.provider — 'google' or 'openai-compatible'
• mcpServers — array of { name, url }
• maxSteps — max tool-call rounds before forcing text generation
• maxToolResultChars / maxContextChars — truncation limits
• tokenTransferPrompt — system prompt for replying to incoming token transfers
• cacheMessages — set false to disable SDK-side DM caching (default true)
• oracle.trustBasePath / oracle.debug — optional aggregator overrides

mcp-rag does semantic search over Markdown files in rag/:

• Index is rebuilt on every container start (Chroma DB is persisted at data/mcp-rag/chromadb/).
• Section-aware chunking preserves header context.

To update:

# edit rag/*.md
docker compose restart mcp-rag

mkdir -p packages/mcp-myservice/src

// packages/mcp-myservice/src/server.ts
import { createServer } from 'node:http';
import { randomUUID } from 'node:crypto';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { z } from 'zod';

const server = new McpServer({ name: 'myservice', version: '1.0.0' });

server.tool(
  'my_tool',
  'Description of what this tool does',
  { input: z.string().describe('Input parameter') },
  async ({ input }) => ({
    content: [{ type: 'text', text: JSON.stringify({ result: input }) }],
  }),
);

const port = parseInt(process.env.PORT || '3004');
const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: () => randomUUID(),
});
await server.connect(transport);

createServer((req, res) => {
  if (req.url === '/mcp') transport.handleRequest(req, res);
  else { res.writeHead(404); res.end('Not Found'); }
}).listen(port, () => console.log(`MCP server on port ${port}`));

Add the service to docker-compose.yml (see mcp-web / mcp-rag for patterns) and reference its URL in the relevant bot's mcpServers config.

• TypeScript ES modules ("type": "module", NodeNext resolution); use .js extensions in imports.
• Bots default to testnet; flip with the *_NETWORK env var.
• MCP connections are persistent — restart the bot container if a connection issue surfaces.
• No tests currently. Test infrastructure was removed alongside the old agent-server frontend.

• Model Context Protocol
• Vercel AI SDK v6
• Sphere SDK