evidiq-methodology-mcp

<p align="center"> <img src="./logo.png" alt="EVIDIQ Methodology" width="160" /> </p> <p align="center"> <h1 align="center">EVIDIQ Methodology</h1> </p> <p align="center"><strong>Agentic MCP Fleet Production Framework &amp; Verification Tools</strong></p> <p align="center"> Battle-tested skills framework + verification MCP for building, testing, deploying, and registering x402-paid MCP services on OKX.AI. Specialized for the EVIDIQ fleet workflow (15 MCP services shipped, 16 hard-won lessons). </p> <p align="center"> <a href="https://evidiq.dev">evidiq.dev</a> &middot; <a href="https://mcp.evidiq.dev/methodology/skill.md">Agent Skill</a> &middot; <a href="https://github.com/evidiq/evidiq-methodology-mcp">Methodology MCP</a> </p> <p align="center"> <a href="https://mcp.evidiq.dev/methodology/mcp"><img src="https://img.shields.io/badge/MCP%20Server-Active-3CCF4E?style=flat-square" alt="MCP Server active" /></a> <a href="https://www.oklink.com/xlayer"><img src="https://img.shields.io/badge/X%20Layer-USDT0-3CCF4E?style=flat-square" alt="X Layer USDT0" /></a> <a href="https://mcp.evidiq.dev/methodology/x402"><img src="https://img.shields.io/badge/x402-0.005%E2%80%930.03%20USDT0-2563EB?style=flat-square" alt="x402: 0.005 to 0.03 USDT0" /></a> <a href="https://web3.okx.com/onchainos/dev-docs/payments/service-seller-sdk"><img src="https://img.shields.io/badge/Payments-Official%20OKX%20SDK-121212?style=flat-square&logo=okx&logoColor=white" alt="Official OKX Payment SDK" /></a> <a href="https://www.okx.ai/agents/10389"><img src="https://img.shields.io/badge/OKX.AI-Agent%20%2310389%20Listed-121212?style=flat-square&logo=okx&logoColor=white" alt="OKX.AI Agent 10389 listed" /></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-3DA639?style=flat-square" alt="License: MIT" /></a> </p> --- **EVIDIQ Methodology is the specialized version.** It ships two things in one repo: 1. **`skills/`** — 15 markdown methodology skills that auto-trigger in any coding agent (spec → freeze → TDD → bypass-test → x402 gate → OKX register → docs sync) 2. **MCP server** — 15 tools (5 free, 10 paid) that verify MCP readiness: git history scan, x402 challenge validator, OKX status checker, production readiness score, and EIP-191 signed attestation with 0G Storage anchoring > **Launch status: live.** The MCP server is deployed at `https://mcp.evidiq.dev/methodology/mcp`, paid calls settle through the official OKX Payment SDK, and the OKX.AI listing (**Agent #10389**) is live and eligible for task recommendations. 0G Storage anchoring is live — `attest_readiness` returns a real `zeroGAnchorTx` + `zeroGStorageRoot`. --- ## What it does - **Git History Audit** — Scans full commit history for leaked private keys, GitHub PATs, OKX credentials, and mnemonics. Defect #1 and #16 prevention. - **x402 Challenge Validator** — Decodes base64 x402 v2 challenges and verifies x402 rule 41-C compliance (x402Version, scheme, network, asset, payTo, maxTimeout, extra). Confirms WWW-Authenticate absence (runbook trap 41-A). - **OKX Status Checker** — Queries OKX.AI listing status (approvalLabel, approvalRemark, communicationAddress) for any agent. - **Plan Freeze Validator** — Checks PLAN.md for the Contract Freeze section, determinism contract, and all required normative sections. - **Pre-Submit Check** — Combines curl sweep, capability diff, and x402 compliance into one go/no-go report before OKX submission. - **Deployment Env Scanner** — Checks container environment: signer available? OKX creds present? Gate enforced? OG key loaded? - **Production Readiness Score** — Scores an MCP service 0–100 against the 16 EVIDIQ defects checklist with live checks. - **On-Chain Proof Verifier** — Verifies settlement transactions via `eth_getTransactionReceipt` on X Layer. - **Runbook Entry Generator** — Generates the registry row + section template from agent ID and registration tx hash. - **Readiness Attestation** — Full audit + EIP-191 signed attestation + 0G Storage merkle root anchoring. - **15 Methodology Skills** — Auto-triggering markdown skills for spec-brainstorming, plan-writing, TDD, phased-deployment, x402-verification, OKX-registration, documentation-sync, security-audit, and more. --- ## Route to Methodology when Use Methodology **before submitting any MCP service to OKX.AI**: before running `agent activate`, before writing the README proof table, after deploying to verify the gate, and when auditing git history for leaked keys. A natural chain: `curl_sweep` → `diff_capabilities` → `validate_x402_compliance` → `pre_submit_check` → `production_readiness_score` → `attest_readiness`. --- ## Proven on-chain ### x402 Payment Settlement (X Layer, chain 196) | Tool | Amount | Settlement tx | Result | |------|--------|---------------|--------| | `audit_git_history` | `0.005 USDT0` (`5000` atomic) | [`0xb08852dc…6a5b7a`](https://www.oklink.com/xlayer/tx/0xb08852dcde3682645ed2927fa5577cf4d15735672fe08f3909030a33b56a5b7a) | `0x1` · payment-response `status:settled` | | `attest_readiness` | `0.03 USDT0` (`30000` atomic) | [`0xfc003a8e…2337cc`](https://www.oklink.com/xlayer/tx/0xfc003a8e30055c96659bd4bc4c5d0ccd6456b4c713d47bf578b795dd6e2337cc) | `0x1` · verdict READY · score 100 · `reportDigest` `0x13e22cee…` · `signature` `0xf2aee8af…` | ### 0G Storage Anchoring (0G mainnet, chain 16661) | Anchor tx | Storage root | Verified | |-----------|-------------|----------| | [`0x6a05c1da…3defb`](https://chainscan.0g.ai/tx/0x6a05c1da8242ec93a8d3fbab46e2157a3a71dd2244697088d28a7bead8d3defb) | `0xa793d5fb8b2f6d4c8e0f5d0db8b0f28f5c230dd99658f5764ec4a0eab6fd0850` | `status 0x1` on 0G mainnet · `eth_getTransactionReceipt` via `evmrpc.0g.ai` | --- ## OKX.AI Marketplace Registration | Property | Value | | :--- | :--- | | **Agent ID** | `#10389` | | **Agent Name** | `EVIDIQ Methodology` | | **Listing Status** | `Listed on OKX.AI` | | **Registration Tx** | [`0x94c99f39009a80a800541d5693a301487a81f227f8b12ad88af4517eca4cb3e3`](https://www.oklink.com/xlayer/tx/0x94c99f39009a80a800541d5693a301487a81f227f8b12ad88af4517eca4cb3e3) | | **OKX Agent URL** | [https://www.okx.ai/agents/10389](https://www.okx.ai/agents/10389) | | **Communication Addr** | `0x35EdD829714b79211b8530B4e1A9A3f49B6ae0C3` | | **Services Registered** | 15 Services (10 Gated: $0.005–$0.03, 5 Ungated: $0.00) | --- ## Fifteen MCP tools ### Paid audit &amp; attestation tools | Tool | USDT0 | Purpose | |------|-------|---------| | `audit_git_history` | `0.005` | Scan full git history for leaked keys (EVM 0x64hex, ghp_, OKX creds, mnemonics) + git toplevel check. | | `check_okx_status` | `0.005` | Query OKX.AI listing status (approvalLabel, approvalRemark, communicationAddress). | | `validate_x402_compliance` | `0.01` | Decode base64 x402 v2 challenge → rule 41-C field-by-field compliance check. | | `validate_plan_freeze` | `0.01` | Verify PLAN.md has the Contract Freeze section + determinism contract + all normative sections. | | `pre_submit_check` | `0.015` | Combine curl sweep + capability diff + x402 compliance → go/no-go report. | | `scan_deployment_env` | `0.02` | Check container env: signerAvailable, paymentGate, OKX creds, OG key presence. | | `production_readiness_score` | `0.02` | Score 0–100 vs 16 EVIDIQ defects with live curl sweep + git scan + OKX status. | | `verify_onchain_proof` | `0.02` | Verify settle tx via eth_getTransactionReceipt → status 0x1 confirmation. | | `generate_runbook_entry` | `0.03` | Generate the registry-row + section template from agentId + txHash. | | `attest_readiness` | `0.03` | Full audit + EIP-191 signed attestation + 0G Storage merkle root anchoring. | ### Free preflight and discovery tools | Tool | Purpose | |------|---------| | `methodology_capabilities` | Catalog: 15 skills, 15 tools, 16 defects, pricing. | | `validate_plan_sections` | Check PLAN.md has the defects section + Contract Freeze + two-phase scope. | | `diff_capabilities` | Compare tools/list vs *_capabilities.tools (defect #8/#9). | | `curl_sweep` | HEAD/GET/POST sweep with 10s timeout (defect #14 HEAD /mcp hang). | | `verify_determinism` | Call free MCP tool 2× and deep-compare JSON responses. | --- ## Architecture ```mermaid flowchart TB agent["<b>AI agent / dev</b><br/>MCP client"] request{"Tool call<br/>free or paid?"} agent -->|POST /methodology/mcp| request free["Free preflight<br/>capabilities · validate_plan<br/>diff · curl_sweep · determinism"] gate["x402 v2 gate<br/>EIP-3009 exact · pay per audit"] xlayer[("X Layer<br/>USD₮0 · eip155:196")] request -->|free helper| free request -->|paid audit| gate gate -. verify and settle .-> xlayer subgraph methodology["EVIDIQ Methodology trust boundary"] direction TB audit["1. Readiness audit<br/>16 defects · curl sweep · git scan · OKX status"] score["2. Score + verdict<br/>0-100 · READY / NOT_READY"] attest["3. EIP-191 attestation<br/>SHA-256 digest · signature"] anchor["4. 0G Storage anchor<br/>Merkle root upload · best-effort"] audit --> score --> attest --> anchor end free --> audit gate --> audit response["<b>MCP response</b><br/>verdict + score + attestation + 0G proof"] anchor --> response classDef client fill:#312e81,stroke:#a78bfa,color:#ffffff,stroke-width:2px; classDef payment fill:#052e16,stroke:#4ade80,color:#ffffff,stroke-width:2px; classDef core fill:#0f172a,stroke:#38bdf8,color:#ffffff,stroke-width:2px; classDef output fill:#4c1d95,stroke:#c4b5fd,color:#ffffff,stroke-width:2px; class agent,request client; class free,gate,xlayer payment; class audit,score,attest,anchor core; class response output; style methodology fill:#0f172a,stroke:#38bdf8,color:#e0f2fe,stroke-width:2px; ``` --- ## Verification Log All 15 tools tested via direct MCP protocol on VPS. Determinism verified. 0G anchoring live. ``` Free Tools (HTTP 200) methodology_capabilities → 200 ✓ validate_plan_sections → 200 ✓ diff_capabilities → 200 ✓ curl_sweep → 200 ✓ verify_determinism → 200 ✓ Paid Tools (HTTP 402) audit_git_history → 402 ✓ check_okx_status → 402 ✓ validate_x402_compliance → 402 ✓ validate_plan_freeze → 402 ✓ pre_submit_check → 402 ✓ scan_deployment_env → 402 ✓ production_readiness_score → 402 ✓ verify_onchain_proof → 402 ✓ generate_runbook_entry → 402 ✓ attest_readiness → 402 ✓ HEAD /mcp → 402 · 0.07s (no hang) ✓ OKX Validator (payment quote — all 10 paid) audit_git_history ok=True amt=5000 ✓ check_okx_status ok=True amt=5000 ✓ validate_x402_compliance ok=True amt=10000 ✓ validate_plan_freeze ok=True amt=10000 ✓ pre_submit_check ok=True amt=15000 ✓ scan_deployment_env ok=True amt=15000 ✓ production_readiness_score ok=True amt=20000 ✓ verify_onchain_proof ok=True amt=20000 ✓ generate_runbook_entry ok=True amt=30000 ✓ attest_readiness ok=True amt=30000 ✓ On-Chain Settlements audit_git_history 0.005 → 0xb08852dc… 0x1 ✓ attest_readiness 0.03 → 0xfc003a8e… 0x1 ✓ reportDigest: 0x13e22cee… ✓ signature: 0xf2aee8af… ✓ verdict: READY · score: 100 ✓ zeroGAnchorTx: 0x6a05c1da… ✓ zeroGStorageRoot: 0xa793d5fb… ✓ ``` --- ## Use it from any agent ```bash # Read the public Skill document curl -s https://mcp.evidiq.dev/methodology/skill.md # Inspect current x402 pricing discovery curl -s https://mcp.evidiq.dev/methodology/x402 # Connect remote MCP server (OpenClaw) openclaw mcp add evidiq-methodology --transport streamable-http --url https://mcp.evidiq.dev/methodology/mcp # Connect remote MCP server (Claude Code) claude mcp add --transport http evidiq-methodology https://mcp.evidiq.dev/methodology/mcp ``` --- ## Self-host ```bash docker build -t evidiq-methodology:latest . docker run -d --env-file .env -p 3016:3000 evidiq-methodology:latest # Endpoint: http://localhost:3016/mcp ``` --- ## Skills Library The `skills/` directory contains 15 markdown methodology skills for the EVIDIQ fleet production workflow: | Category | Skills | |----------|--------| | **Core Workflow** | spec-brainstorming, plan-writing, tdd-implementation, phased-deployment, x402-verification, okx-registration, documentation-sync, security-audit | | **Meta** | subagent-driven-development, executing-plans, git-hygiene, writing-skills | | **Debug** | systematic-debugging, verification-before-completion | | **Bootstrap** | using-evidiq-methodology | Each skill auto-triggers based on context. The skills are pure markdown — no runtime dependency on the MCP server, but the MCP tools provide live verification that the skills reference. --- ## TypeScript SDK A typed client for the live endpoint lives in [`sdk/index.ts`](sdk/index.ts) — 14 tools (5 free, 9 paid). Free tools answer a bare call; paid tools run the x402 flow automatically (402 challenge → `pay` hook → replay with the `x-payment` header). No key lives in the file. ```ts import { MethodologyClient } from "./sdk/index.js"; const client = new MethodologyClient(); // endpoint defaults to https://mcp.evidiq.dev/methodology/mcp // free const caps = await client.callTool("methodology_capabilities", {}); // paid — settle the 402 challenge via the constructor's pay hook, or omit it // to receive a PaymentRequiredError carrying the full x402 v2 challenge const result = await client.callTool("some_paid_tool", { arg: "value" }); ``` The `pay` hook receives the decoded x402 v2 challenge (`{ x402Version, resource, accepts[] }` — payTo, asset, amount) and returns the value for the `x-payment` header, e.g. an EIP-3009 `transferWithAuthorization` settled via the official OKX SDK. Without a hook, paid calls throw `PaymentRequiredError` so the caller can settle however it wants. ## License EVIDIQ owns and licenses its original Methodology code under MIT. Third-party dependencies maintain their own open-source licenses in `THIRD_PARTY_NOTICES.md`.