Skip to content

MCP_API_GUIDE.md

Latest commit

 

History

History
503 lines (317 loc) · 8.62 KB

MCP_API_GUIDE.md

File metadata and controls

503 lines (317 loc) · 8.62 KB

NeriaMind MCP Tools & API Reference

Complete guide to all 14 MCP tools and 10 REST API endpoints

🔌 Access Methods

MCP (AI Agents)

  • Server: http://localhost:9200/mcp
  • Auth: OAuth 2.1 (Bearer token with neriamind scope)
  • Clients: Cursor, VS Code, Claude Desktop, etc.

REST API

📚 MCP Tools (14 Total)

Content Fetching (2 tools)

neriamind-fetch-wikipedia

Retrieve Wikipedia content via MediaWiki API.

Input:

  • topic (string): Wikipedia page title

Returns: Summary, images, videos, full content flag

Example:

{
  "topic": "Quantum_computing",
  "title": "Quantum computing",
  "summary": "Quantum computing is...",
  "url": "https://en.wikipedia.org/wiki/Quantum_computing",
  "images": [...],
  "videos": [...]
}

neriamind-fetch-grokopedia

Scrape Grokipedia content via Puppeteer.

Input:

  • topic (string): Topic name

Returns: Summary, content, images, videos, fact-check metadata

Content Analysis (1 tool)

neriamind-compare-encyclopedia

Multi-modal comparison of Wikipedia vs Grokipedia.

Input:

  • topic (string): Topic to compare
  • wikipediaOverride (string, optional): Manual Wikipedia content
  • grokopediaOverride (string, optional): Manual Grokipedia content
  • publish (boolean, optional): Publish Truth Note to DKG
  • visibility ('public'|'private', optional): Asset visibility
  • epochs (number, 1-24, optional): Storage duration

Returns:

{
  "topic": "Quantum_computing",
  "divergenceScore": 0.24,
  "similarity": 0.76,
  "discrepancies": {
    "factualInconsistencies": [...],
    "missingContext": [...],
    "aiHallucinations": [...],
    "bias": [...]
  },
  "analysis": {
    "textSimilarity": 0.85,
    "imageSimilarity": 0.90,
    "structuralDifferences": [...]
  },
  "ual": "did:dkg:otp:20430/..." // If published
}

Truth Note Operations (2 tools)

neriamind-get-truth-note

Retrieve truth note by UAL.

Input:

  • ual (string): Knowledge Asset UAL
  • includeMetadata (boolean, optional): Include metadata

Returns: Truth Note assertion data (JSON-LD)

neriamind-list-truth-notes

List published truth notes.

Input:

  • topic (string, optional): Filter by topic
  • publisher (string, optional): Filter by publisher
  • limit (number, max 100, optional): Result limit

Returns: Array of truth notes with UALs

Topic Management (4 tools)

neriamind-publish-designated-topics

Publish curated topics to DKG.

Input:

  • topics (array, optional): Custom topics
  • useCuratedTopics (boolean, optional): Use 8 predefined topics
  • visibility ('public'|'private', optional)
  • epochs (number, 1-24, optional)

Returns: Published topics with UALs and Explorer links

8 Curated Topics:

  1. Quantum_computing
  2. Climate_change
  3. Artificial_intelligence
  4. Bitcoin
  5. Elon_Musk
  6. COVID-19_pandemic
  7. Renewable_energy
  8. Machine_learning

neriamind-fetch-designated-topics

Query published topics from DKG.

Input:

  • publisherAddress (string, optional): Filter by publisher
  • source ('NeriaMind'|'all', optional): Filter by source
  • ualList (array, optional): Direct UAL list
  • limit (number, max 100, optional)

Returns: List of topics with metadata

neriamind-process-designated-topics

End-to-end workflow: Query → Compare → Publish.

Input:

  • publisherAddress (string, optional)
  • source ('NeriaMind'|'all', optional)
  • ualList (array, optional)
  • limit (number, max 50, optional)
  • publishNotes (boolean, optional): Auto-publish notes
  • visibility ('public'|'private', optional)
  • epochs (number, 1-24, optional)

Returns: Processing results with all UALs

neriamind-fetch-topic-assets

Search DKG for topic-related Knowledge Assets.

Input:

  • topic (string): Topic name
  • limit (number, max 100, optional)

Returns: Matching Knowledge Assets

DKG Queries (2 tools)

neriamind-query-dkg

Execute SPARQL queries on DKG.

Input:

  • query (string): SPARQL query
  • queryType ('SELECT'|'CONSTRUCT'|'ASK'|'DESCRIBE', optional)
  • paranetUAL (string, optional): Scope to paranet

Returns: Query results

neriamind-search-topics

Search topics in published truth notes.

Input:

  • query (string): Search query
  • limit (number, max 100, optional)

Returns: Matching truth notes

Trust Layer (3 tools)

neriamind-pay-truth-note

Access premium content via x402 payment.

Input:

  • ual (string): Truth note UAL

Returns: Payment status and invoice

Requires: FACILITATOR_PRIVATE_KEY in .env

neriamind-stake-truth-note

Stake tokens on truth note accuracy.

Input:

  • ual (string): Truth note UAL
  • amount (number): Stake amount
  • token ('TRAC'|'NEURO'): Token type

Returns: Stake confirmation

neriamind-trust-summary

Get confidence metrics for truth note.

Input:

  • ual (string): Truth note UAL

Returns:

{
	"confidenceScore": 0.991,
	"totalStaked": { "TRAC": 300, "NEURO": 50 },
	"stakerCount": 3,
	"verificationStatus": "verified",
	"isPremium": true
}

🌐 REST API Endpoints (10 Total)

NeriaMind Plugin Endpoints

Base Path: /neriamind/* Auth: OAuth 2.1 Bearer token with neriamind scope

POST /neriamind/compare

Compare Wikipedia vs Grokipedia for a topic.

Body:

{
	"topic": "Quantum_computing",
	"publish": true,
	"visibility": "public",
	"epochs": 6
}

Response: Comparison result with UAL (if published)

GET /neriamind/truth-note?ual={ual}

Retrieve truth note (moved to root /truth-note for x402).

POST /neriamind/designated-topics/publish

Publish curated topics to DKG.

Body:

{
	"useCuratedTopics": true,
	"visibility": "public",
	"epochs": 6
}

GET /neriamind/designated-topics

Query published topics from DKG.

Query Params:

  • publisherAddress (optional)
  • source (optional)
  • limit (optional, max 100)

POST /neriamind/payments/x402/pay

Simulated x402 payment (MCP tool available).

GET /neriamind/payments/x402/status?invoiceId={id}

Check payment status.

GET /neriamind/trust/stakes?ual={ual}

List stakes for truth note (MCP tool available).

x402 Facilitator Endpoints (Root Level)

Base Path: /facilitator/* Auth: Public (no auth required for protocol compliance)

GET /facilitator/supported

List supported payment networks.

Response:

{
	"kinds": [
		{
			"x402Version": 1,
			"scheme": "exact",
			"network": "neuroweb-testnet"
		}
	]
}

POST /facilitator/verify

Verify payment signature.

Body: Payment signature data Response: Verification result

POST /facilitator/settle

Settle payment on NeuroWeb blockchain.

Body: Payment details Response: Transaction hash

Truth Note Access (Root Level)

Base Path: /truth-note Auth: Public (x402 handles access control)

GET /truth-note?ual={ual}

Retrieve truth note (402 for premium).

Response:

  • Free notes: HTTP 200 + truth note data
  • Premium notes: HTTP 402 + payment requirements

Trust Layer Endpoints (Root Level)

Base Path: /trust/* Auth: Public

POST /trust/stake

Record stake on truth note.

Body:

{
	"ual": "did:dkg:otp:20430/...",
	"amount": 100,
	"token": "TRAC",
	"staker": "0x..."
}

GET /trust/stakes?ual={ual}

List all stakes for truth note.

GET /trust/metrics?ual={ual}

Calculate confidence metrics.

Response:

{
	"confidenceScore": 0.991,
	"totalStaked": { "TRAC": 300, "NEURO": 50 },
	"stakerCount": 3,
	"verificationStatus": "verified",
	"isPremium": true
}

🧪 Quick Testing

# Test facilitator
curl http://localhost:9200/facilitator/supported

# Test premium note (402)
curl http://localhost:9200/truth-note?ual=did:dkg:otp:20430/0x...01/1

# Test staking
curl -X POST http://localhost:9200/trust/stake \
  -H "Content-Type: application/json" \
  -d '{"ual":"test","amount":100,"token":"TRAC","staker":"0xTest"}'

# Check metrics
curl http://localhost:9200/trust/metrics?ual=test

📚 Interactive Documentation

Swagger UI: http://localhost:9200/swagger

All endpoints are documented with:

  • Request/response schemas
  • Example payloads
  • Try-it-out functionality

For detailed architecture: See ARCHITECTURE.md For setup instructions: See README.md