coherence-mcp-server 0.3.1 → 0.4.1

package/README.md

@@ -1,9 +1,8 @@
-<!-- AUTO-GENERATED from README.template.md. Edit the template, not this file. -->
 # coherence-mcp-server
 
 **Give your AI agent native access to every idea, spec, contributor, and value chain in the Coherence Network.**
 
-An [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes the full Coherence Network API as 20 typed tools — so Claude, Cursor, Windsurf, or any MCP-compatible agent can browse ideas, look up specs, trace value lineage, link identities, and record contributions without writing a single API call.
+An [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes the full Coherence Network API as 51 typed tools — so Claude, Cursor, Windsurf, or any MCP-compatible agent can browse ideas, look up specs, trace value lineage, link identities, record contributions, execute tasks, and evolve the project graph without writing a single API call.
 
 ```bash
 npx coherence-mcp-server
@@ -22,7 +21,12 @@ This MCP server changes that. It gives any agent a typed interface to:
 - **Discover** — browse ideas ranked by ROI, search specs, see what's resonating
 - **Trace** — follow value from idea through spec, implementation, usage, and payout
 - **Attribute** — link any of 37 identity providers, record contributions, check ledgers
-- **Govern** — view change requests, federation nodes, and network health
+- **Execute** — participate in the agent work pipeline (claim tasks, report results)
+- **Evolve** — create new ideas, link dependencies, and navigate the universal graph
+- **Finance** — track treasury balances, record deposits, and monitor assets
+- **Signal** — ingest news, track trending keywords, and measure concept resonance
+- **Ontology** — explore the Living Codex (184 universal concepts, 53 axes)
+- **Govern** — propose changes, vote on requests, and monitor network health
 
 Every tool returns structured JSON. No parsing HTML. No scraping. Just clean data.
 
@@ -69,7 +73,7 @@ Point your MCP client at `npx coherence-mcp-server` via stdio transport.
 
 ---
 
-## Tools (20)
+## Tools (51)
 
 ### Ideas — the portfolio engine
 
@@ -77,6 +81,8 @@ Point your MCP client at `npx coherence-mcp-server` via stdio transport.
 |------|-------------|
 | `coherence_list_ideas` | Browse ideas ranked by ROI and free-energy score. Filter with `search`, limit with `limit`. |
 | `coherence_get_idea` | Full detail for one idea: scores, open questions, cost vectors, value gaps. |
+| `coherence_create_idea` | Create a new idea in the portfolio. |
+| `coherence_update_idea` | Update an existing idea (stage, status, metadata). |
 | `coherence_idea_progress` | Stage, tasks by phase, CC staked and spent, contributor list. |
 | `coherence_select_idea` | Let the portfolio engine pick the next highest-ROI idea. `temperature` controls explore vs exploit. |
 | `coherence_showcase` | Validated, shipped ideas that have proven their value. |
@@ -112,45 +118,84 @@ Point your MCP client at `npx coherence-mcp-server` via stdio transport.
 | `coherence_record_contribution` | Record work by contributor name or by provider identity (no registration needed). |
 | `coherence_contributor_ledger` | CC balance, contribution history, and linked ideas. |
 
-### Network health & governance
+### Tasks — agent work protocol
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_tasks` | See what tasks are pending, running, or failed. |
+| `coherence_get_task` | Full task details, direction, and result. |
+| `coherence_task_next` | Claim the highest-priority pending task. |
+| `coherence_task_claim` | Claim a specific task by ID. |
+| `coherence_task_report` | Report task as completed or failed with output. |
+| `coherence_task_seed` | Create a new task from an idea. |
+| `coherence_task_events` | View the activity event log for a task. |
+
+### Graph — universal navigation
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_edges` | List relationship edges with filters. |
+| `coherence_get_entity_edges` | Incoming and outgoing edges for any entity. |
+| `coherence_create_edge` | Create a typed edge between two entities. |
+
+### Assets — tracked artifacts
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_assets` | List tracked assets (code, docs, endpoints). |
+| `coherence_get_asset` | Detail for a specific asset by UUID. |
+| `coherence_create_asset` | Register a new tracked asset. |
+
+### News & Signals
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_get_news_feed` | Latest news from RSS sources with POV ranking. |
+| `coherence_get_news_resonance` | Match news to ideas with explanations. |
+| `coherence_list_news_sources` | List all configured RSS sources. |
+| `coherence_add_news_source` | Add a new RSS source to the ingestion engine. |
+| `coherence_get_trending_news` | Trending keywords from recent coverage. |
+
+### Treasury — financial operations
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_get_treasury_info` | Conversion rates, addresses, and CC totals. |
+| `coherence_record_deposit` | Record crypto deposit and convert to CC. |
+| `coherence_get_deposit_history` | History of deposits for a contributor. |
+
+### Governance — decision workflows
 
 | Tool | What it does |
 |------|-------------|
-| `coherence_status` | API health, uptime, idea count, federation node count. |
-| `coherence_friction_report` | Where the pipeline struggles — friction signals over a time window. |
 | `coherence_list_change_requests` | Open governance proposals. |
+| `coherence_get_change_request` | Detail for a specific proposal. |
+| `coherence_vote_governance` | Cast a 'yes' or 'no' vote on a proposal. |
+| `coherence_propose_governance` | Create a new governance change request. |
+
+### Living Codex ontology
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_concepts` | Browse 184 universal concepts with 53 axes. |
+| `coherence_get_concept` | Full concept detail with typed relationship edges. |
+| `coherence_link_concepts` | Create typed relationships between concepts. |
+
+### Health & Integrity
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_status` | API health, uptime, idea count, federation node count. |
+| `coherence_friction_report` | Where the pipeline struggles. |
 | `coherence_list_federation_nodes` | Federated nodes and their capabilities. |
+| `coherence_get_dif_stats` | DIF verification accuracy statistics. |
+| `coherence_get_recent_dif` | Recent DIF verification entries and scores. |
 
 ---
 
 ## CLI equivalent
 
-The Coherence CLI (`npm i -g coherence-cli`) provides the same capabilities as the MCP tools, plus additional commands. Here is the mapping:
-
-| MCP Tool | CLI Command |
-|----------|------------|
-| `coherence_list_ideas` | `cc ideas` |
-| `coherence_get_idea` | `cc idea <id>` |
-| `coherence_idea_progress` | `cc idea <id>` (includes progress) |
-| `coherence_select_idea` | `cc ideas` (with temperature flag) |
-| `coherence_showcase` | `cc ideas` (showcase view) |
-| `coherence_resonance` | `cc resonance` |
-| `coherence_list_specs` | `cc specs` |
-| `coherence_get_spec` | `cc spec <id>` |
-| `coherence_list_lineage` | `cc lineage` |
-| `coherence_lineage_valuation` | `cc lineage <id> valuation` |
-| `coherence_list_providers` | `cc providers` |
-| `coherence_link_identity` | `cc identity link <provider> <handle>` |
-| `coherence_lookup_identity` | `cc identity lookup <provider> <handle>` |
-| `coherence_get_identities` | `cc identity` |
-| `coherence_record_contribution` | `cc contribute` |
-| `coherence_contributor_ledger` | `cc contributor <id> contributions` |
-| `coherence_status` | `cc status` |
-| `coherence_friction_report` | `cc friction` |
-| `coherence_list_change_requests` | `cc governance` |
-| `coherence_list_federation_nodes` | `cc nodes` |
-
-The CLI also includes additional commands not available via MCP: `cc news`, `cc treasury`, `cc assets`, `cc services`, `cc trace`, `cc diag`, and more. Run `cc help` for the full list of 54 commands.
+The Coherence CLI (`npm i -g coherence-cli`) provides the same capabilities as the MCP tools. Run `cc help` for the full list of 54 commands.
 
 ---
 
@@ -161,93 +206,22 @@ Once connected, you can ask your agent things like:
 - *"What ideas have the highest ROI right now?"*
 - *"Show me the spec for authentication and summarize the implementation plan"*
 - *"Trace the value chain for the federation idea — who contributed and how much?"*
+- *"What are the trending keywords in the news today and which ideas do they resonate with?"*
 - *"Link my GitHub identity and record a code contribution for the CLI work I did"*
 - *"What's the network friction report for the last 30 days?"*
 - *"Pick the next best idea for me to work on"*
+- *"Create a new idea for 'Automated PR reviews' and link it as enabling the 'GitHub integration' idea"*
 
 The agent calls the right tools, gets structured data, and responds naturally.
 
 ---
 
-## How coherence scoring works
-
-Every idea and contribution is scored 0.0–1.0:
-
-- **1.0** — Tests pass, docs clear, implementation simple, value proven
-- **0.5** — Partial coverage, work in progress
-- **0.0** — No evidence of quality or value
-
-Payouts are weighted by coherence. Higher-quality work earns proportionally more. The score is a signal, not a grade — it tells the network how much trust the work has earned.
-
----
-
 ## Environment variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `COHERENCE_API_URL` | `https://api.coherencycoin.com` | API base URL. Override to point at a local node. |
-| `COHERENCE_API_KEY` | *(none)* | API key for write operations. See below for what requires a key and how to get one. |
-
-### What requires an API key?
-
-**No key needed (read-only):** Browse ideas, search specs, view lineage, check contributor ledgers, see federation nodes, read coherence scores, view governance proposals.
-
-**Key needed (write operations):** Update idea status, record contributions, link identities, create specs, vote on governance proposals, manage federation nodes, submit news sources.
-
-Most users start without a key — exploring ideas, reading specs, checking who's contributing. You only need a key when you're ready to actively contribute.
-
-### How to get an API key
-
-Run the interactive setup:
-
-```bash
-npx coherence-cli
-# then: cc setup
-```
-
-This walks you through:
-1. Choose a contributor name
-2. Link an identity (GitHub, Discord, Ethereum, etc.)
-3. The system generates an API key tied to your identity
-
-Your key is stored locally in `~/.coherence-network/config.json` and used automatically by both the CLI and MCP server.
-
-**Manual setup** (if you already have a key):
-
-```bash
-export COHERENCE_API_KEY="your-key-here"
-npx coherence-mcp-server
-```
-
-Or in your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "coherence-network": {
-      "command": "npx",
-      "args": ["coherence-mcp-server"],
-      "env": {
-        "COHERENCE_API_KEY": "your-key-here"
-      }
-    }
-  }
-}
-```
-
-Source code: [github.com/seeker71/Coherence-Network/mcp-server](https://github.com/seeker71/Coherence-Network/tree/main/mcp-server)
-
----
-
-## The five pillars
-
-| Pillar | What it means for agents |
-|--------|-------------------------|
-| **Traceability** | Every tool call traces back to real ideas, real specs, real contributors. |
-| **Trust** | Coherence scores give agents objective quality signals — no guessing. |
-| **Freedom** | Federated nodes, open governance. No single point of control. |
-| **Uniqueness** | Every entity is uniquely identified. No duplicate ideas, no ambiguous specs. |
-| **Collaboration** | Agents and humans contribute side by side, credited fairly. |
+| `COHERENCE_API_KEY` | *(none)* | Required for write operations (governance, spec creation, federation). Reads work without a key. |
 
 ---
 
@@ -260,21 +234,12 @@ Every part of the network links to every other. Jump in wherever makes sense.
 | **Web** | Browse ideas, specs, and contributors visually | [coherencycoin.com](https://coherencycoin.com) |
 | **API** | 100+ endpoints, full OpenAPI docs, the engine behind everything | [api.coherencycoin.com/docs](https://api.coherencycoin.com/docs) |
 | **CLI** | Terminal-first access — `npm i -g coherence-cli` then `cc help` | [npm: coherence-cli](https://www.npmjs.com/package/coherence-cli) |
-| **MCP Server** | This package — 20 typed tools for AI agents | [npm: coherence-mcp-server](https://www.npmjs.com/package/coherence-mcp-server) |
+| **MCP Server** | This package — 51 typed tools for AI agents | [npm: coherence-mcp-server](https://www.npmjs.com/package/coherence-mcp-server) |
 | **OpenClaw Skill** | Auto-triggers in any OpenClaw instance for ideas, specs, coherence | [ClawHub: coherence-network](https://clawhub.com/skills/coherence-network) |
 | **GitHub** | Source code, specs, issues, and contribution tracking | [github.com/seeker71/Coherence-Network](https://github.com/seeker71/Coherence-Network) |
 
 ---
 
-## Get involved
-
-Coherence Network is open source. Every contribution — human or agent — is tracked and fairly attributed.
-
-- **Start exploring**: Add the MCP server to your agent and ask *"What ideas need work?"*
-- **GitHub**: [github.com/seeker71/Coherence-Network](https://github.com/seeker71/Coherence-Network)
-
----
-
 ## License
 
 MIT

package/README.template.md

@@ -2,7 +2,7 @@
 
 **Give your AI agent native access to every idea, spec, contributor, and value chain in the Coherence Network.**
 
-An [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes the full Coherence Network API as 20 typed tools — so Claude, Cursor, Windsurf, or any MCP-compatible agent can browse ideas, look up specs, trace value lineage, link identities, and record contributions without writing a single API call.
+An [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes the full Coherence Network API as 51 typed tools — so Claude, Cursor, Windsurf, or any MCP-compatible agent can browse ideas, look up specs, trace value lineage, link identities, record contributions, execute tasks, and evolve the project graph without writing a single API call.
 
 ```bash
 npx coherence-mcp-server
@@ -21,7 +21,12 @@ This MCP server changes that. It gives any agent a typed interface to:
 - **Discover** — browse ideas ranked by ROI, search specs, see what's resonating
 - **Trace** — follow value from idea through spec, implementation, usage, and payout
 - **Attribute** — link any of 37 identity providers, record contributions, check ledgers
-- **Govern** — view change requests, federation nodes, and network health
+- **Execute** — participate in the agent work pipeline (claim tasks, report results)
+- **Evolve** — create new ideas, link dependencies, and navigate the universal graph
+- **Finance** — track treasury balances, record deposits, and monitor assets
+- **Signal** — ingest news, track trending keywords, and measure concept resonance
+- **Ontology** — explore the Living Codex (184 universal concepts, 53 axes)
+- **Govern** — propose changes, vote on requests, and monitor network health
 
 Every tool returns structured JSON. No parsing HTML. No scraping. Just clean data.
 
@@ -68,7 +73,7 @@ Point your MCP client at `npx coherence-mcp-server` via stdio transport.
 
 ---
 
-## Tools (20)
+## Tools (51)
 
 ### Ideas — the portfolio engine
 
@@ -76,6 +81,8 @@ Point your MCP client at `npx coherence-mcp-server` via stdio transport.
 |------|-------------|
 | `coherence_list_ideas` | Browse ideas ranked by ROI and free-energy score. Filter with `search`, limit with `limit`. |
 | `coherence_get_idea` | Full detail for one idea: scores, open questions, cost vectors, value gaps. |
+| `coherence_create_idea` | Create a new idea in the portfolio. |
+| `coherence_update_idea` | Update an existing idea (stage, status, metadata). |
 | `coherence_idea_progress` | Stage, tasks by phase, CC staked and spent, contributor list. |
 | `coherence_select_idea` | Let the portfolio engine pick the next highest-ROI idea. `temperature` controls explore vs exploit. |
 | `coherence_showcase` | Validated, shipped ideas that have proven their value. |
@@ -111,14 +118,84 @@ Point your MCP client at `npx coherence-mcp-server` via stdio transport.
 | `coherence_record_contribution` | Record work by contributor name or by provider identity (no registration needed). |
 | `coherence_contributor_ledger` | CC balance, contribution history, and linked ideas. |
 
-### Network health & governance
+### Tasks — agent work protocol
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_tasks` | See what tasks are pending, running, or failed. |
+| `coherence_get_task` | Full task details, direction, and result. |
+| `coherence_task_next` | Claim the highest-priority pending task. |
+| `coherence_task_claim` | Claim a specific task by ID. |
+| `coherence_task_report` | Report task as completed or failed with output. |
+| `coherence_task_seed` | Create a new task from an idea. |
+| `coherence_task_events` | View the activity event log for a task. |
+
+### Graph — universal navigation
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_edges` | List relationship edges with filters. |
+| `coherence_get_entity_edges` | Incoming and outgoing edges for any entity. |
+| `coherence_create_edge` | Create a typed edge between two entities. |
+
+### Assets — tracked artifacts
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_assets` | List tracked assets (code, docs, endpoints). |
+| `coherence_get_asset` | Detail for a specific asset by UUID. |
+| `coherence_create_asset` | Register a new tracked asset. |
+
+### News & Signals
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_get_news_feed` | Latest news from RSS sources with POV ranking. |
+| `coherence_get_news_resonance` | Match news to ideas with explanations. |
+| `coherence_list_news_sources` | List all configured RSS sources. |
+| `coherence_add_news_source` | Add a new RSS source to the ingestion engine. |
+| `coherence_get_trending_news` | Trending keywords from recent coverage. |
+
+### Treasury — financial operations
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_get_treasury_info` | Conversion rates, addresses, and CC totals. |
+| `coherence_record_deposit` | Record crypto deposit and convert to CC. |
+| `coherence_get_deposit_history` | History of deposits for a contributor. |
+
+### Governance — decision workflows
 
 | Tool | What it does |
 |------|-------------|
-| `coherence_status` | API health, uptime, idea count, federation node count. |
-| `coherence_friction_report` | Where the pipeline struggles — friction signals over a time window. |
 | `coherence_list_change_requests` | Open governance proposals. |
+| `coherence_get_change_request` | Detail for a specific proposal. |
+| `coherence_vote_governance` | Cast a 'yes' or 'no' vote on a proposal. |
+| `coherence_propose_governance` | Create a new governance change request. |
+
+### Living Codex ontology
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_list_concepts` | Browse 184 universal concepts with 53 axes. |
+| `coherence_get_concept` | Full concept detail with typed relationship edges. |
+| `coherence_link_concepts` | Create typed relationships between concepts. |
+
+### Health & Integrity
+
+| Tool | What it does |
+|------|-------------|
+| `coherence_status` | API health, uptime, idea count, federation node count. |
+| `coherence_friction_report` | Where the pipeline struggles. |
 | `coherence_list_federation_nodes` | Federated nodes and their capabilities. |
+| `coherence_get_dif_stats` | DIF verification accuracy statistics. |
+| `coherence_get_recent_dif` | Recent DIF verification entries and scores. |
+
+---
+
+## CLI equivalent
+
+The Coherence CLI (`npm i -g coherence-cli`) provides the same capabilities as the MCP tools. Run `cc help` for the full list of 54 commands.
 
 ---
 
@@ -129,26 +206,16 @@ Once connected, you can ask your agent things like:
 - *"What ideas have the highest ROI right now?"*
 - *"Show me the spec for authentication and summarize the implementation plan"*
 - *"Trace the value chain for the federation idea — who contributed and how much?"*
+- *"What are the trending keywords in the news today and which ideas do they resonate with?"*
 - *"Link my GitHub identity and record a code contribution for the CLI work I did"*
 - *"What's the network friction report for the last 30 days?"*
 - *"Pick the next best idea for me to work on"*
+- *"Create a new idea for 'Automated PR reviews' and link it as enabling the 'GitHub integration' idea"*
 
 The agent calls the right tools, gets structured data, and responds naturally.
 
 ---
 
-## How coherence scoring works
-
-Every idea and contribution is scored 0.0–1.0:
-
-- **1.0** — Tests pass, docs clear, implementation simple, value proven
-- **0.5** — Partial coverage, work in progress
-- **0.0** — No evidence of quality or value
-
-Payouts are weighted by coherence. Higher-quality work earns proportionally more. The score is a signal, not a grade — it tells the network how much trust the work has earned.
-
----
-
 ## Environment variables
 
 | Variable | Default | Description |
@@ -158,18 +225,6 @@ Payouts are weighted by coherence. Higher-quality work earns proportionally more
 
 ---
 
-## The five pillars
-
-| Pillar | What it means for agents |
-|--------|-------------------------|
-| **Traceability** | Every tool call traces back to real ideas, real specs, real contributors. |
-| **Trust** | Coherence scores give agents objective quality signals — no guessing. |
-| **Freedom** | Federated nodes, open governance. No single point of control. |
-| **Uniqueness** | Every entity is uniquely identified. No duplicate ideas, no ambiguous specs. |
-| **Collaboration** | Agents and humans contribute side by side, credited fairly. |
-
----
-
 ## The Coherence Network ecosystem
 
 Every part of the network links to every other. Jump in wherever makes sense.
@@ -179,21 +234,12 @@ Every part of the network links to every other. Jump in wherever makes sense.
 | **Web** | Browse ideas, specs, and contributors visually | [coherencycoin.com](https://coherencycoin.com) |
 | **API** | 100+ endpoints, full OpenAPI docs, the engine behind everything | [api.coherencycoin.com/docs](https://api.coherencycoin.com/docs) |
 | **CLI** | Terminal-first access — `npm i -g coherence-cli` then `cc help` | [npm: coherence-cli](https://www.npmjs.com/package/coherence-cli) |
-| **MCP Server** | This package — 20 typed tools for AI agents | [npm: coherence-mcp-server](https://www.npmjs.com/package/coherence-mcp-server) |
+| **MCP Server** | This package — 51 typed tools for AI agents | [npm: coherence-mcp-server](https://www.npmjs.com/package/coherence-mcp-server) |
 | **OpenClaw Skill** | Auto-triggers in any OpenClaw instance for ideas, specs, coherence | [ClawHub: coherence-network](https://clawhub.com/skills/coherence-network) |
 | **GitHub** | Source code, specs, issues, and contribution tracking | [github.com/seeker71/Coherence-Network](https://github.com/seeker71/Coherence-Network) |
 
 ---
 
-## Get involved
-
-Coherence Network is open source. Every contribution — human or agent — is tracked and fairly attributed.
-
-- **Start exploring**: Add the MCP server to your agent and ask *"What ideas need work?"*
-- **GitHub**: [github.com/seeker71/Coherence-Network](https://github.com/seeker71/Coherence-Network)
-
----
-
 ## License
 
 MIT

package/coherence_mcp_server/__init__.py

@@ -0,0 +1,17 @@
+"""
+coherence-mcp-server — MCP server for the Coherence Network.
+
+22 typed tools for AI agents to browse ideas, trace value chains,
+link identities, record contributions, and explore the Living Codex ontology.
+
+Usage:
+    python -m coherence_mcp_server
+    coherence-mcp-server
+
+Environment variables:
+    COHERENCE_API_URL   API base URL (default: https://api.coherencycoin.com)
+    COHERENCE_API_KEY   API key for write operations (optional for reads)
+"""
+
+__version__ = "0.3.1"
+__all__ = ["__version__"]

package/coherence_mcp_server/__main__.py

@@ -0,0 +1,20 @@
+"""Entry point for coherence-mcp-server Python package.
+
+Run via:
+    python -m coherence_mcp_server
+    coherence-mcp-server        (after pip install)
+    uvx coherence-mcp-server    (via uv)
+"""
+
+import asyncio
+import sys
+
+
+def main() -> None:
+    """Start the Coherence Network MCP server."""
+    from coherence_mcp_server.server import run
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    sys.exit(main())