Skip to content

API.md

Latest commit

 

History

History
295 lines (210 loc) · 7.1 KB

API.md

File metadata and controls

295 lines (210 loc) · 7.1 KB
Raw

MisakaNet API Reference

Version: 2.17.0 | Protocol: misaka-protocol.json

MisakaNet exposes a multi-surface API: CLI search, MCP tools, GitHub-based contribution endpoints, and optional Hub federation. This document catalogues every supported interface.

1. CLI Search API (search_knowledge.py)

The primary entry point for knowledge retrieval.

Usage

python3 search_knowledge.py "<query>" [flags]

Flags

Flag Description
--lessons Search only lesson files
--ref Search only reference documents
--titles Match against titles only
--domain <name> Filter by domain (e.g., python, docker)
--semantic Enable semantic search (requires sentence-transformers)
--explain Show score breakdowns and match reasons
--json Output results as JSON
--top N Limit to top N results (default: 10)
--verbose Show detailed scoring metadata

JSON Output Schema

{
  "title": "Lesson title",
  "domain": "python",
  "tags": ["tag1", "tag2"],
  "score": 0.8765,
  "path": "lessons/domain/filename.md",
  "preview": "First 120 characters...",
  "match_reason": "title + body match",
  "preview_highlighted": "First 120 chars with <mark>...</mark>",
  "confidence": "high",
  "result_type": "lesson",
  "score_breakdown": {
    "bm25": 0.8234,
    "title_boost": 1.5,
    "tag_match": 1.2,
    "final": 0.8765
  }
}

Exit Codes

Code Meaning
0 Success — results returned
1 Search failed or no results found

2. MCP Tools (Model Context Protocol)

Two transports are available: stdio (local) and HTTP/SSE (remote).

2.1 Stdio Transport (scripts/mcp_server.py)

python3 scripts/mcp_server.py

Exposes 4 tools via MCP stdio protocol:

Tool Parameters Returns
misakanet.search query (str), domain? (str), top? (int=5) Ranked lesson results
misakanet.get_lesson path_or_id (str) Full lesson markdown content
misakanet.submit_usage lesson_id (str), tool (str), outcome (str) Confirmation
misakanet.usage_status user? (str) Usage statistics

Claude Code Configuration

{
  "mcpServers": {
    "misakanet": {
      "command": "python3",
      "args": ["C:/path/to/MisakaNet/scripts/mcp_server.py"]
    }
  }
}

2.2 HTTP/SSE Transport (scripts/mcp_http_server.py)

python3 scripts/mcp_http_server.py [--port 8080]

Started on http://localhost:8080/mcp by default. Compatible with any MCP client supporting Streamable HTTP transport.

Cursor / Continue Configuration

{
  "mcpServers": {
    "misakanet-http": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

2.3 MCP Protocol Metadata

Server identity advertised at connection:

{
  "name": "misakanet",
  "version": "2.16.0",
  "description": "MisakaNet knowledge search and contribution"
}

3. Contribution API (scripts/contribute.py)

Submit lessons directly via GitHub API — no fork or git push required.

Usage

# Submit a pre-written .md file
python3 scripts/contribute.py path/to/lesson.md

# Create a lesson inline
python3 scripts/contribute.py -t "Title" -d domain --tags "tag1,tag2" "Content body..."

Requirements

  • GITHUB_TOKEN environment variable (or ~/.git-credentials)
  • PR is created against Ikalus1988/MisakaNet:main
  • Branch is auto-named lesson/<slug>

API Flow

  1. Get default branch SHA (GET /repos/Ikalus1988/MisakaNet/git/ref/heads/main)
  2. Create blob (POST /repos/Ikalus1988/MisakaNet/git/blobs)
  3. Create tree (POST /repos/Ikalus1988/MisakaNet/git/trees)
  4. Create commit (POST /repos/Ikalus1988/MisakaNet/git/commits)
  5. Create branch ref (POST /repos/Ikalus1988/MisakaNet/git/refs)
  6. Create PR (POST /repos/Ikalus1988/MisakaNet/pulls)

Queue Lesson API (scripts/queue_lesson.py)

python3 scripts/queue_lesson.py \
  -t "Title" -d domain \
  --tags "node:name,project:name" \
  "Problem\n\n## Root Cause\n...\n\n## Fix\n...\n\n## Verification\n..."

4. Hub Federation API (Optional)

The Hub provides a lightweight sync scheduler with optional federation.

4.1 Hub Sync Scheduler (hub/misaka_hub.py)

python3 hub/misaka_hub.py
Mode Description
Standalone Periodic git fetch + knowledge graph rebuild
Master Master API for multi-node coordination
Federation HMAC-authenticated inter-node sync

4.2 Master API (hub/master/master_api.py)

Endpoint Method Description
/status GET Node health and sync status
/nodes GET Registered node directory
/sync/trigger POST Force immediate sync

4.3 Federation HMAC Auth (hub/federation/hmac_auth.py)

# Node-to-node authentication with shared secret
from hub.federation.hmac_auth import sign_request, verify_request

signed = sign_request(payload, secret_key)
verified = verify_request(signed, secret_key)

4.4 Knowledge Graph (hub/storage/knowledge_graph.py)

from hub.storage.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()
kg.build()           # Rebuild from lessons/
kg.query("concept")  # Semantic query

5. Notifier API

Optional notification channels for sync events.

5.1 Discord / Slack / Email (hub/sync/notifier.py)

Configure via environment variables:

Variable Purpose
DISCORD_WEBHOOK_URL Discord notification webhook
SLACK_WEBHOOK_URL Slack incoming webhook
EMAIL_SMTP_HOST SMTP server for email
EMAIL_TO Recipient address

5.2 Feishu (Lark) (hub/sync/feishu_notifier.py)

Variable Purpose
FEISHU_WEBHOOK_URL Feishu bot webhook URL

6. Verification Tools

scripts/misaka_verify.py

python3 scripts/misaka_verify.py

Validates protocol configuration against misaka-protocol.json.

scripts/validate_lessons.py

python3 scripts/validate_lessons.py [--strict]

Checks all lesson frontmatter for schema compliance.

scripts/site_health_check.py

python3 scripts/site_health_check.py

End-to-end health check of deployed services.

7. Python SDK Imports

# Core search engine
from misakanet.search.engine import MisakaNetSearchEngine, _search_cached, LESSONS

# Lesson scoring
from misakanet.tools.lesson_scorer import score_lessons, format_lesson_scores

# BM25 via ecosystem package
from misakanet_core import BM25, tokenize, rrf

# Node profile
from misakanet.profile import NodeProfile

# Evidence tracking
from misakanet.evidence import EvidenceTracker

8. Rate Limits & Error Handling

  • GitHub API: Standard rate limits apply (5000 req/h authenticated)
  • MCP stdio: Single-connection, no built-in rate limiting
  • MCP HTTP: No built-in rate limiting — use a reverse proxy for production
  • Search: L1/L2 caching built into misakanet.search.engine
  • Notifiers: Exponential backoff on webhook failures (3 retries, 2s/4s/8s)