@pnlmarket/mcp-server 0.4.0

package/skills/pnl-notify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pnl-notify
+description: Show recent PNL notifications for the local wallet — votes on your markets, resolutions, claim-ready alerts. Stateful (last-seen tracking) and on-demand.
+---
+
+# /pnl-notify
+
+The user wants to know what's happened on PNL since they last
+checked — votes on their markets, market resolutions, claim-ready
+alerts, milestones.
+
+## What to do
+
+### Step 1 — call pnl_notify
+
+Pass `{}` for the default behavior (new items since last call, top
+10, unread only). The tool reads the local wallet address from the
+encrypted-at-rest store and queries `/api/notifications` for that
+wallet.
+
+If the user asks for the *full* feed (not just what's new), pass
+`{ all: true }`. If they want read items too, pass `{ unreadOnly:
+false }`.
+
+### Step 2 — surface the items
+
+The tool returns a table:
+
+| Type | When (UTC) | Title | Market / Token |
+
+Plus the user's profile URL (`/profile/<wallet>`) so they can open
+it to mark items read or drill into specifics.
+
+### Step 3 — suggest follow-ups based on type
+
+- `claim_ready` → suggest `/pnl-claim-now` (or `/pnl-claim`)
+- `market_resolved` → mention the resolution side
+- `vote_result` on a market the user created → suggest checking
+  `/pnl-get-market` for the live pool state
+- `pool_complete` → market may be eligible for early resolution
+
+## State management
+
+The tool writes the most recent notification timestamp to
+`~/.config/pnl/last-seen.json` keyed by wallet address. To re-show
+everything (e.g. if the user wants to scan the full inbox), pass
+`{ all: true }` — that ignores the last-seen cursor.
+
+## When to invoke proactively
+
+- After `/pnl-pitch-now` or `/pnl-vote-now` succeeds and the user
+  asks "what's next" — they may want to see how their existing
+  positions are doing.
+- When the user opens a session and says "any updates?".
+
+Do not auto-poll without being asked; this is an on-demand tool.
+For background polling, use `/loop /pnl-notify` from the user side.

package/skills/pnl-pitch/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pnl-pitch
+description: Pitch an idea on PNL. Extracts the idea from the conversation context, asks the user for any missing fields, then returns a deep-link they open to sign + post the market.
+---
+
+# /pnl-pitch
+
+The user wants to turn an idea (often something that surfaced in the
+agent conversation just before they invoked this skill) into a live
+conviction market on PNL.
+
+## What to do
+
+### Step 1 — extract what you can from context
+
+Look back over the recent conversation for:
+
+- **name**: the idea's name (e.g. "AutoImport CLI")
+- **description**: 1-3 sentences describing what it is and why it
+  matters. Pull from the user's own words when possible — be honest
+  about the idea, not overhyped.
+- **tokenSymbol**: a 3-10 character uppercase ticker. If not stated,
+  propose one derived from the name (e.g. AutoImport CLI → AUTOIMP).
+  Confirm with the user before posting.
+- **category**: one of DeFi, NFT, Gaming, DAO, AI/ML, Infrastructure,
+  Social, Meme, Creator, Healthcare, Science, Education, Finance,
+  Commerce, Real Estate, Energy, Media, Manufacturing, Mobility, Other.
+  Pick the best fit.
+- **projectType**: Protocol | Application | Platform | Service | Tool.
+  Default to Tool if uncertain.
+- **projectStage**: Idea | MVP | Beta | Production | Scaling | Prototype |
+  Launched. Default Idea if uncertain.
+
+### Step 2 — ask the user for anything still missing
+
+These almost always need user input:
+
+- **teamSize** (default 1 if solo)
+- **targetPoolSol** (typical range 5-50 SOL; common default 15)
+- **durationDays** (typical 7-90; common default 30)
+
+Ask them in one batched question, not one at a time. Example:
+
+> "Got it. Before I draft the market: how big a target pool (in SOL,
+> common is 15) and how long should voting stay open (in days, common
+> is 30)?"
+
+### Step 3 — provenance (optional but on-brand)
+
+If the idea genuinely surfaced from the current conversation — a TODO
+comment, a feature the user mentioned in passing, a problem they were
+discussing — *ask the user* whether to attach a provenance record.
+
+If they say yes, pass `provenance` with:
+- `source: "claude-code"`
+- `excerpt`: the 1-3 sentences from the conversation that birthed the
+  idea (their words, lightly cleaned)
+- `codeSnippet`: any relevant code if it motivated the idea
+- `timestamp`: ISO 8601 of now
+
+This shows up on the market detail page as
+"this idea was born from a conversation in Claude Code on [date]" —
+the AI-builder thesis made literal.
+
+### Step 4 — call pnl_pitch_idea
+
+Pass everything gathered. The tool POSTs to PNL's draft endpoint and
+returns a `https://pnl.market/create?draft=<id>` URL.
+
+### Step 5 — hand off
+
+Tell the user:
+
+> "Drafted. Open this to sign and post: <URL>
+>
+> The /create page is pre-filled with everything I just sent. You'll
+> connect your wallet there and confirm the create_market transaction
+> in your browser. The market goes live as soon as it confirms on-chain
+> (~5-15 seconds on Solana mainnet)."
+
+Don't try to call `pnl_init` or `pnl_wallet` first unless the user
+mentions wallet trouble — the deep-link uses their Privy / external
+browser wallet, not the MCP local keypair (that's Phase B).

package/skills/pnl-pitch-now/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: pnl-pitch-now
+description: Autosign mode — MCP signs the create_market transaction locally with the unlocked wallet, no browser bounce. For pitches whose creation fee fits inside the autosign cap.
+---
+
+# /pnl-pitch-now
+
+Same intent as `/pnl-pitch`, but the MCP signs and sends the
+`create_market` transaction *locally* — the user doesn't have to
+open a browser. Use when the user wants the market posted now,
+without leaving the terminal.
+
+## Prerequisites
+
+The autosign flow needs:
+
+- A wallet on this machine (`pnl_init` previously run)
+- The wallet **unlocked** (`pnl_unlock` first, otherwise the tool
+  fails with a "wallet locked" message)
+- Wallet balance ≥ ~0.02 SOL (creation fee + tx fee)
+- The creation fee within the autosign cap (defaults 0.05 SOL, can
+  be overridden per-call via `autosignCapSol`)
+
+If the wallet isn't unlocked, fall back to `/pnl-pitch` (deep-link
+mode) — the user can sign in their browser without an unlock.
+
+## What to do
+
+### Step 1 — extract the idea from context
+
+Identical to `/pnl-pitch`: gather name, description, tokenSymbol,
+category, projectType, projectStage from the conversation, propose
+defaults where reasonable, and confirm with the user.
+
+### Step 2 — gather remaining fields
+
+Ask in one batched question:
+
+- `teamSize` (default 1)
+- `targetPoolSol` (typical 5-50, common default 15)
+- `durationDays` (typical 7-90, common default 30)
+
+### Step 3 — provenance (same as /pnl-pitch)
+
+If the idea genuinely surfaced from the current conversation, ask
+whether to attach a `provenance` record with `source: "claude-code"`,
+`excerpt`, optional `codeSnippet`, `timestamp`. Threads through to the
+market page as "born from a conversation in Claude Code on [date]".
+
+### Step 4 — confirm the user wants autosign
+
+Before calling the tool, surface what's about to happen in one
+sentence:
+
+> "I'll sign the create_market tx locally with your wallet
+> (`<truncated-address>`). That's a ~0.015 SOL creation fee plus a
+> ~0.000005 SOL Solana fee. Confirm?"
+
+If the user wants the deep-link flow instead, switch to
+`/pnl-pitch`.
+
+### Step 5 — call pnl_pitch_now
+
+Pass the same payload as `pnl_pitch_idea` plus any
+`autosignCapSol` override.
+
+### Step 6 — hand off the result
+
+The tool returns the live market URL + tx signature + Solscan link.
+Tell the user:
+
+> "Market live: <URL>
+>  Tx: <signature> (Solscan: <link>)
+>  The MCP signed and sent locally — no browser bounce."
+
+## Failure modes to handle gracefully
+
+- **Wallet locked**: tool throws "Wallet is locked." → suggest
+  `/pnl-unlock` then re-run.
+- **Insufficient balance**: tool throws balance check error →
+  show the deposit address from `pnl_wallet` and suggest funding.
+- **Exceeds cap**: tool throws cap-exceeded → either ask the user to
+  raise the cap (pass `autosignCapSol` larger) or switch to
+  `/pnl-pitch` deep-link.
+- **Tx confirmed but complete-create failed**: tool throws with the
+  tx signature — the market exists on-chain, just the off-chain
+  metadata didn't persist. Re-running `pnl_pitch_now` with the same
+  args is idempotent on `marketAddress`. Recommend that.

package/skills/pnl-restore/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pnl-restore
+description: Restore a PNL wallet on this machine from a BIP39 mnemonic (12 or 24 words). Use on a new machine when the user already has the recovery phrase.
+---
+
+# /pnl-restore
+
+The user wants to set up PNL on a new machine using the BIP39 mnemonic
+from a previous `pnl_init`.
+
+## What to do
+
+1. Ask the user for their 12 or 24 word recovery phrase. Confirm
+   they're typing it in a context they trust — once they paste it in
+   chat, anyone who reads the conversation transcript could in
+   principle reconstruct the wallet. This is the standard wallet-
+   restore tradeoff.
+2. Call the `pnl_restore` MCP tool with `{ mnemonic: <phrase> }`. If a
+   wallet already exists on the machine, the tool will refuse unless
+   you pass `allowOverwrite: true` — only do this if the user
+   explicitly says to replace the existing wallet (and ideally after
+   they've run `/pnl-export` to back it up).
+3. The tool will prompt for a fresh passphrase via OS dialog. The
+   user types it there, not in chat.
+4. On success: confirm the restored address and tell the user the
+   wallet is unlocked for 30 minutes.
+
+## Common follow-ups
+
+- "Why do I need a new passphrase?" → The passphrase encrypts the
+  wallet at rest on THIS machine. It's independent of the mnemonic
+  (which is what actually controls the funds). You can use the same
+  passphrase as before, or pick a new one for this machine.
+- "What if I lost the mnemonic?" → If the user has access to ANY
+  machine where the wallet was previously initialized AND knows the
+  passphrase for it, they can run `pnl_export_keypair` to retrieve
+  the secret. Without either, the funds are unrecoverable — that's
+  the harsh reality of self-custody.

package/skills/pnl-unlock/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: pnl-unlock
+description: Unlock the PNL wallet for signing. Passphrase is requested via OS-native dialog or PNL_PASSPHRASE env var — never via chat.
+---
+
+# /pnl-unlock
+
+The user wants to enable signing on their PNL wallet for the current
+session.
+
+## What to do
+
+1. Call the `pnl_unlock` MCP tool. Optional arg: `ttlMinutes` (default 5).
+2. The tool will request the user's passphrase via PNL_PASSPHRASE env
+   or by popping an OS-native dialog. **You will never see the
+   passphrase.** Relay the response.
+3. On success: confirm the wallet is unlocked and for how long.
+4. On failure ("passphrase is incorrect"): suggest the user re-run the
+   command; the passphrase prompt will reappear.
+
+## Important
+
+Never offer to put the passphrase in a tool argument or chat message.
+The whole point of the unlock flow is that the passphrase stays out of
+the conversation. If the user types their passphrase in chat anyway,
+mention that they should rotate the wallet (pnl_export_keypair, send
+funds to a fresh pnl_init, restore on the same machine with new
+passphrase via pnl_restore).

package/skills/pnl-vote/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pnl-vote
+description: Stake YES or NO on an existing PNL market. Returns a deep-link with side + amount pre-filled; user signs in their wallet.
+---
+
+# /pnl-vote
+
+The user wants to stake YES or NO on an existing PNL conviction
+market. This is the "back this idea" or "fade this idea" action.
+
+## What to do
+
+### Step 1 — figure out which market
+
+If the user said "vote yes on Nakshatra" or named a market, run
+`pnl_browse_markets` (or `pnl_get_market` if they gave an id) to
+confirm the market id. The deep-link uses that id.
+
+### Step 2 — confirm side + amount
+
+Ask the user for any missing fields:
+
+- **vote**: `yes` (back) or `no` (fade)
+- **amountSol**: minimum 0.01 SOL on most markets; typical
+  retail-sized vote is 0.01-1 SOL. If the user said "small" treat
+  as 0.05, "modest" as 0.1, "real money" ask explicitly.
+
+Skip Step 2 if the user gave both inline (e.g. "vote yes on Nakshatra
+with 0.1 SOL").
+
+### Step 3 — call pnl_vote
+
+Pass `{ marketId, vote, amountSol }`. The tool returns a deep-link.
+
+### Step 4 — hand off
+
+Tell the user to open the URL. The market page pre-fills the vote
+panel from the query params, so they only confirm + sign in their
+browser wallet. Transaction confirms in ~5-15s on Solana mainnet.
+
+## Common follow-ups
+
+- "Why two clicks?" → v0.2 is deep-link mode (no local signing).
+  Phase B will add autosign for stakes under the cap.
+- "What does NO actually win?" → NO voters split the pool if NO
+  wins. Critics get paid for filtering noise. Tell them to read
+  the manifesto at docs.pnl.market/docs/manifesto for the
+  protocol's stance on skepticism as a paid role.

package/skills/pnl-vote-now/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pnl-vote-now
+description: Autosign mode — MCP signs the buy_yes / buy_no transaction locally with the unlocked wallet, no browser bounce. For stakes inside the autosign cap.
+---
+
+# /pnl-vote-now
+
+Same intent as `/pnl-vote`, but the MCP signs and sends the
+`buy_yes` / `buy_no` transaction *locally* — the user doesn't open
+a browser. Use when the user wants to stake immediately without
+leaving the terminal.
+
+## Prerequisites
+
+- Wallet on this machine (`pnl_init` previously run)
+- Wallet **unlocked** (`pnl_unlock` first)
+- Wallet balance ≥ `amountSol + ~0.001 SOL` (stake + tx-fee buffer)
+- `amountSol` within the autosign cap (defaults 0.05 SOL, can be
+  overridden per-call via `autosignCapSol`)
+
+For larger stakes, use `/pnl-vote` — the deep-link flow is the right
+tool when the user explicitly wants to bigger amount approval-flow.
+
+## What to do
+
+### Step 1 — figure out which market
+
+If the user named a market, run `pnl_browse_markets` (or
+`pnl_get_market` with the id) to confirm and grab its identifier.
+The tool accepts either the Mongo id or the on-chain market address.
+
+### Step 2 — confirm side + amount
+
+If not given inline, ask:
+
+- `vote`: `yes` (back) or `no` (fade)
+- `amountSol`: minimum 0.01 SOL
+
+If the user said "small", treat as 0.05; "modest", 0.1; "real money",
+ask explicitly.
+
+### Step 3 — confirm autosign
+
+Before calling the tool, surface in one sentence:
+
+> "I'll sign a `buy_<side>` tx locally for `<amountSol>` SOL with
+> your wallet. Confirm?"
+
+### Step 4 — call pnl_vote_now
+
+Pass `{ marketId, vote, amountSol }` and any `autosignCapSol`
+override.
+
+### Step 5 — hand off
+
+The tool returns the tx signature + Solscan link + market URL.
+Pool movement is visible immediately at the market URL.
+
+## Failure modes to handle gracefully
+
+- **Wallet locked** → suggest `/pnl-unlock` first.
+- **Stake exceeds cap** → either raise `autosignCapSol` or switch to
+  `/pnl-vote` deep-link.
+- **Insufficient balance** → show address from `pnl_wallet`, suggest
+  funding.
+- **Tx confirmed but complete-vote failed** → the on-chain vote
+  landed; re-running `pnl_vote_now` is idempotent on the tx
+  signature. Recommend a retry.

package/skills/pnl-wallet/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: pnl-wallet
+description: Show the local PNL wallet's address, balance, and autosign cap. Use to check if a funding transaction has landed.
+---
+
+# /pnl-wallet
+
+The user wants to see the current state of their local PNL wallet.
+
+## What to do
+
+1. Call the `pnl_wallet` MCP tool with no arguments.
+2. Relay the response. It contains:
+   - Public address (the deposit address)
+   - Current SOL balance
+   - Autosign cap (the per-tx SOL limit below which the MCP server
+     signs without confirmation — Phase B feature)
+   - Active RPC endpoint
+3. If the balance is 0, suggest the user fund the wallet by sending SOL
+   to the address from any Solana wallet.
+4. If the tool returns "No PNL wallet on this machine yet", suggest
+   they run `/pnl-init` first.