agentleFS
refined-elementrefined-element/lightning-enable-mcp/CLAUDE.md

lightning-enable-mcp

CLAUDE.md9 starsChanged 36 days agoMITView on GitHub

Part of Lightning Enable — infrastructure for agent commerce over Lightning. Open-source (MIT) MCP server for AI agent Lightning payments. See the main repo at F:\lightning-enable for full context. Publishing: Bump the version in ALL SIX files in the SAME commit, then push to main: 1. dotnet/src/LightningEnable.Mcp/LightningEnable.Mcp.csproj — <Version> 2. python/lightning-enable-mcp/pyproject.toml — version 3. server.json — .version, both .packages[].version (nuget + pypi), and the Docker image pin in .packages[2].identifier (docker.io/refinedelement/lightning-enable-mcp:<version>) 4. mcpb/manifest.json — .version 5. mcpb/pyproject.toml — version and the…

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When a bug is reported, do NOT immediately start trying to fix it.

    line 64
  2. Distinctive:

    User-facing error messages: Never return blank/empty responses on failure.

    line 73
  3. Distinctive:

    Never log sensitive data: Never log API keys, wallet credentials, macaroons, preimages, or NWC connection strings.

    line 75
  4. Distinctive:

    Secret key exposure: If any credentials are potentially leaked (in logs, responses, git history), flag to the user IMMEDIATELY.

    line 76

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md — Lightning Enable MCP

Project Overview

Part of Lightning Enable — infrastructure for agent commerce over Lightning.

Open-source (MIT) MCP server for AI agent Lightning payments. See the main repo at F:\lightning-enable for full context.

Publishing: Bump the version in ALL SIX files in the SAME commit, then push to main:

  1. dotnet/src/LightningEnable.Mcp/LightningEnable.Mcp.csproj — <Version>
  2. python/lightning-enable-mcp/pyproject.toml — version
  3. server.json — .version, both .packages[].version (nuget + pypi), and the Docker image pin in .packages[2].identifier (docker.io/refinedelement/lightning-enable-mcp:<version>)
  4. mcpb/manifest.json — .version
  5. mcpb/pyproject.toml — version and the lightning-enable-mcp==<version> dependency pin
  6. dotnet/src/LightningEnable.Mcp/Services/UserAgent.cs — FallbackVersion (the last-resort User-Agent version, used only if the assembly has no version). UserAgentTests fails the .NET suite on drift; publish-mcp.yml does not check it.

publish-mcp.yml's verify-versions job checks the first five and fails the whole publish on any drift (2.0.3 was caught this way).

server.json is committed source-of-truth for the MCP Registry entry — it is NOT rewritten at publish time. publish-mcp.yml verifies it matches the release version and fails the registry publish on any drift, so a partial bump (e.g. csproj/pyproject bumped but server.json left stale) is caught before it strands registry.modelcontextprotocol.io on an old version. server.json's description must be ≤100 chars (also enforced by MCP Registry and CI validation).

Approval channel (out-of-band confirmation)

Over-threshold payments require a human-relayed confirmation code. The code is the operator's, never the model's — it must never appear in a tool result on any channel, and a payment is never approved because its notification could not be delivered (a delivery failure REFUSES the payment and withdraws the minted code).

This is an operator confirmation aid on a trusted local host, not an independent approval boundary: an agent whose host can read the server's console, logs, approval file, or webhook sink can read the code. Guards: at most 3 outstanding codes (MaxPendingConfirmations); 5 consecutive invalid verify/consume attempts revoke every pending code (MaxFailedConfirmationAttempts); TTL confirmation.ttlSeconds / LIGHTNING_ENABLE_CONFIRMATION_TTL_SECONDS, default 120, clamped 30-900 (300-600 suits webhook/file). verify_confirmation_code never echoes the code or destination.

Where the code goes is configurable, because stderr is only out-of-band when a human is watching the console:

confirmation.channelBehaviour
stderr (default)Print the code to the server console. The historical local behaviour, unchanged.
refuseRefuse over-threshold payments. No pending confirmation is created at all.
webhookPOST the pending confirmation to confirmation.webhookUrl, signed X-LightningEnable-Signature: t=…,v1=… (HMAC-SHA256 over {t}.{body}) with confirmation.webhookSecret. Goes through the SSRF-guarded client; never follows redirects; a 3xx or non-2xx is a delivery failure.
fileAppend the same JSON line to confirmation.filePath (default ~/.lightning-enable/confirmations.jsonl), 0600 on POSIX.

Precedence: LIGHTNING_ENABLE_CONFIRMATION_CHANNEL > confirmation.channel > auto. Auto keeps stderr unless stdin is not a TTY and LIGHTNING_ENABLE_HOSTED=1, which selects refuse; a non-TTY stdin alone only earns a one-line startup warning (stdio MCP servers always have a piped stdin). An unparseable channel name fails closed to refuse.

Key files — the two ports mirror each other and must stay in sync:

  • .NET: Models/ConfirmationSettings.cs, Models/ConfirmationRequest.cs, Services/ConfirmationChannelResolver.cs, Services/ConfirmationChannels.cs, Services/ConfirmationChannelFactory.cs, BudgetService.RequestConfirmationAsync.
  • Python: confirmation_channel.py, config.ConfirmationSettings, BudgetService.request_confirmation.

Payment tools MUST call RequestConfirmationAsync / request_confirmation rather than minting a code themselves — that single entry point is what enforces the refuse path and the fail-closed cancel.

Bug Fix Workflow

When a bug is reported, do NOT immediately start trying to fix it. Follow this process:

  1. Write a failing test first — Reproduce the bug with a test that proves it fails
  2. Fix the bug — Use subagents to implement the fix
  3. Prove the fix — Show the test now passes

Engineering Standards

Inherited from Lightning Enable — these apply to all ecosystem properties.

  1. User-facing error messages: Never return blank/empty responses on failure. Always provide descriptive error context.
  2. Graceful error handling: Handle all errors gracefully. Never let unhandled exceptions crash the process or leak stack traces.
  3. Never log sensitive data: Never log API keys, wallet credentials, macaroons, preimages, or NWC connection strings. Use safe identifiers only.
  4. Secret key exposure: If any credentials are potentially leaked (in logs, responses, git history), flag to the user IMMEDIATELY.
  5. Enterprise scale: Flag any patterns that won't scale to hundreds of thousands of concurrent users.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.