litcoin-mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,88 +1,48 @@
 # LITCOIN MCP Server
 
-MCP server for the [LITCOIN](https://litcoiin.xyz) proof-of-comprehension protocol on Base. Gives any AI agent full protocol access through the Model Context Protocol.
+MCP server for the LITCOIN protocol on Base. Mine, research, stake, vault, compute, guilds — all from any MCP-compatible AI agent. 25 tools, including 6 research tools.
 
-## Setup
+## Install
 
-### Claude Desktop / Claude Code
-
-Add to your MCP config (`claude_desktop_config.json` or `.claude.json`):
+Add to your MCP config (Claude Desktop, Cursor, etc.):
 
 ```json
 {
   "mcpServers": {
     "litcoin": {
       "command": "npx",
-      "args": ["-y", "litcoin-mcp"],
-      "env": {
-        "BANKR_API_KEY": "bk_YOUR_KEY"
-      }
+      "args": ["litcoin-mcp"],
+      "env": { "BANKR_API_KEY": "bk_YOUR_KEY" }
     }
   }
 }
 ```
 
-### Cursor
+## Tools (25)
 
-Add to `.cursor/mcp.json`:
+**Mining**: mine, claim, claimable, faucet
+**Balances**: balance, network
+**Staking**: stake, unstake
+**Vaults**: open_vault, mint, repay, add_collateral, close_vault, vaults
+**Compute**: deposit_escrow, compute
+**Guilds**: create_guild, join_guild, leave_guild
+**Research**: research_tasks, research_get_task, research_submit, research_results, research_stats, research_history
 
-```json
-{
-  "mcpServers": {
-    "litcoin": {
-      "command": "npx",
-      "args": ["-y", "litcoin-mcp"],
-      "env": {
-        "BANKR_API_KEY": "bk_YOUR_KEY"
-      }
-    }
-  }
-}
-```
+## Research Mining
 
-Get a Bankr API key at [bankr.bot/api](https://bankr.bot/api).
+Agents can browse optimization tasks, submit solutions, and track their iteration history — all through natural language:
 
-## Available Tools
+> "Show me research tasks" → lists active tasks with baselines
+> "Submit this sorting solution" → verifies and rewards if it beats baseline
+> "Show my research history" → iteration progress per task
 
-| Tool | Description |
-|------|-------------|
-| `litcoin_balance` | Check LITCOIN, LITCREDIT, staking tier, mining boost, escrow balance |
-| `litcoin_network` | Network stats: active miners, treasury, rewards, oracle prices |
-| `litcoin_mine` | Mine one round (solve a comprehension challenge, earn LITCOIN) |
-| `litcoin_claim` | Claim accumulated mining rewards on-chain |
-| `litcoin_claimable` | Check how much is available to claim |
-| `litcoin_stake` | Stake into a tier (1=Spark, 2=Circuit, 3=Core, 4=Architect) |
-| `litcoin_unstake` | Unstake after lock period |
-| `litcoin_open_vault` | Open a vault with LITCOIN collateral |
-| `litcoin_mint` | Mint LITCREDIT against a vault |
-| `litcoin_repay` | Repay LITCREDIT debt |
-| `litcoin_add_collateral` | Add collateral to a vault |
-| `litcoin_close_vault` | Close a vault |
-| `litcoin_vaults` | List all vaults with health ratios |
-| `litcoin_deposit_escrow` | Deposit LITCREDIT for compute spending |
-| `litcoin_compute` | Send a prompt to the compute marketplace |
-| `litcoin_create_guild` | Create a mining guild |
-| `litcoin_join_guild` | Join a guild with deposit |
-| `litcoin_leave_guild` | Leave a guild |
-| `litcoin_faucet` | Claim 5M free LITCOIN (one-time bootstrap) |
-
-## Example Conversation
+## Links
 
-> **You:** Check my LITCOIN balance
->
-> **Agent:** *(calls litcoin_balance)* You have 3,200,000 LITCOIN and 0 LITCREDIT. You're not staked yet.
->
-> **You:** Stake into Circuit tier
->
-> **Agent:** *(calls litcoin_stake with tier=2)* Done! Staked 5M LITCOIN into Circuit tier. Mining boost: 1.25x.
->
-> **You:** Mine 5 rounds
->
-> **Agent:** *(calls litcoin_mine 5 times)* Mined 5 rounds. Earned 750,000 LITCOIN total.
+- Site: https://litcoiin.xyz
+- Research Lab: https://litcoiin.xyz/research
+- SDK: `pip install litcoin`
+- Docs: https://litcoiin.xyz/docs
 
-## Links
+## License
 
-- [LITCOIN Website](https://litcoiin.xyz)
-- [Full Docs (AI-readable)](https://litcoiin.xyz/docs.md)
-- [SDK on PyPI](https://pypi.org/project/litcoin/)
-- [Twitter](https://x.com/litcoin_AI)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litcoin-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MCP server for the LITCOIN proof-of-comprehension protocol on Base. Mine, stake, vault, compute, research — all from any AI agent.",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -668,6 +668,52 @@ server.tool(
   }
 );
 
+server.tool(
+  "litcoin_miner_status",
+  "Get comprehensive miner status: mining activity, relay connection (connected/disconnected), quality score, requests served, earnings breakdown (comprehension/research/staking/relay), guild membership, and overall health check. Essential for debugging relay issues.",
+  {
+    wallet: z.string().optional().describe("Wallet to check (defaults to your wallet)"),
+  },
+  async ({ wallet }) => {
+    const w = wallet || await getWallet();
+    const data = await coordGet(`/v1/miner/status?wallet=${w}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "litcoin_guild_yield",
+  "Get network-wide guild yield data: recent yield distribution history (24h chart data), per-member cumulative yields, total yield earned across all guilds. Shows how the 25% staking pool is distributed to guild members.",
+  {},
+  async () => {
+    const data = await coordGet("/v1/guilds/yield");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "litcoin_guild_member_yield",
+  "Get your personal guild yield history: total yield earned, recent entries for charting, deposit amount, share percentage, and guild ID.",
+  {
+    wallet: z.string().optional().describe("Wallet to check (defaults to your wallet)"),
+  },
+  async ({ wallet }) => {
+    const w = wallet || await getWallet();
+    const data = await coordGet(`/v1/guilds/yield/${w}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "litcoin_protocol_stats",
+  "Get cached protocol statistics: totalStaked, litcreditSupply, vaultCollateral, vaultDebt, cpiPrice, litcoinPrice, treasury balance. Updated every 120 seconds.",
+  {},
+  async () => {
+    const data = await coordGet("/v1/protocol/stats");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
 function solveChallenge(challenge) {
   const { doc, questions, constraints, entities } = challenge;
   if (!doc || !questions) return "";