Smartxcode/Magestack

MCP MageOS Docs Server

Local MCP server that ingests MageOS, Hyvä, and Satoshi documentation, indexes it in SQLite/FTS5, and exposes 60 specialized tools for Claude Desktop, VS Code, and any other MCP-aware host.

Requirements

• Node.js 20+
• npm 9+
• Internet access during crawling
• Optional: GITHUB_TOKEN to avoid rate limits when reading GitHub trees

Installation

npm install
npm run build

Updating the documentation database

# all sources
npm run update
# Hyvä only
npm run update -- --sources=hyva

The SQLite database lives in data/docs.db. Override paths and crawler settings with MCP_DOCS_DB_PATH, MCP_DOCS_DATA_DIR, and the other variables defined in src/config.ts.

Running the MCP server

npm start                # run the compiled CLI
npm run dev              # start via tsx for local development
node dist/cli.js --cron  # enable scheduled refresh

Flags:

• --update – crawl and exit.
• --sources=mageos,hyva – restrict the refresh to selected sources.
• --update-on-start – force a rebuild before the server starts serving requests.
• --cron – enable scheduler mode (default cron: 0 2 * * *).

MCP Tools

• Core utilities: search_docs, get_doc, docs_status, refresh_docs.
• 60 topic-specific commands (hyva_*, mageos_*, satoshi_*) aligned with the scenarios from MCP-Magestack.txt.
• Update triggers exposed as MCP commands: mcp_update_all, mcp_update_hyva, mcp_update_satoshi, mcp_update_mageos.

Project structure

src/
├── cli.ts               # CLI entry point
├── server.ts            # STDIO-based MCP server
├── config.ts            # runtime configuration
├── db/                  # SQLite schema and repository
├── crawlers/            # generic BFS scraper shared by Hyvä/MageOS/Satoshi
├── indexers/            # MageOS/Hyvä/Satoshi crawlers (web + GitHub where available)
├── mcp/                 # tool/topic registration
├── utils/               # http, parsing, hashing, logging
└── update.ts            # standalone update script

Tests & linting

npm run test
npm run lint

Publishing

npm publish --access public

After publishing, configure MCP hosts (e.g., Claude Desktop) as follows:

{
  "mcpServers": {
    "mageosDocs": {
      "command": "npx",
      "args": ["@smartx/mcp-mageos-docs@latest"]
    }
  }
}

################################################################################

Lokalny serwer MCP, który pobiera dokumentację MageOS, Hyvä i Satoshi, indeksuje ją w SQLite/FTS5 i eksponuje 60 narzędzi do natychmiastowego użycia przez hosty MCP (Claude Desktop, VS Code, itp.).

Wymagania

• Node.js 20+
• npm 9+
• Dostęp do internetu podczas indeksowania
• (opcjonalnie) GITHUB_TOKEN dla szybszego rate limitu podczas pobierania repozytoriów

Instalacja

npm install
npm run build

Aktualizacja bazy dokumentacji

# wszystkie źródła
npm run update
# tylko Hyvä
npm run update -- --sources=hyva

Baza SQLite znajduje się w data/docs.db. Środowisko można kontrolować zmiennymi MCP_DOCS_DB_PATH, MCP_DOCS_DATA_DIR i innymi z src/config.ts.

Uruchamianie MCP

npm start                # uruchom build i serwer MCP
npm run dev              # CLI w trybie ts-node/tsx
node dist/cli.js --cron  # uruchom cronowe odświeżanie

Argumenty:

• --update – tylko zindeksuj i zakończ.
• --sources=mageos,hyva – ogranicz aktualizację do wybranych źródeł.
• --update-on-start – wymuś przebudowę indeksu przy starcie serwera MCP.
• --cron – włącz harmonogram aktualizacji (domyślnie 0 2 * * *).

MCP Tools

• search_docs, get_doc, docs_status, refresh_docs
• 60 tematycznych narzędzi (hyva_*, mageos_*, satoshi_*) odpowiadających sekcjom dokumentacji.
• Komendy aktualizacji MCP: mcp_update_all, mcp_update_hyva, mcp_update_satoshi, mcp_update_mageos.

Struktura projektu

src/
├── cli.ts               # punkt wejścia (bin)
├── server.ts            # uruchamia MCP w STDIO
├── config.ts            # konfiguracja źródeł
├── db/                  # schema i repozytorium SQLite
├── crawlers/            # współdzielony BFS crawler
├── indexers/            # crawlerzy MageOS/Hyvä/Satoshi (strony + GitHub tam gdzie trzeba)
├── mcp/                 # rejestracja narzędzi, tematy
├── utils/               # http, parsery, hash, logger
└── update.ts            # skrypt aktualizacji

Testy i lint

npm run test
npm run lint

Publikacja

npm publish --access public

Po publikacji host MCP (np. Claude Desktop) może używać serwera:

{
  "mcpServers": {
    "mageosDocs": {
      "command": "npx",
      "args": ["@smartx/mcp-mageos-docs@latest"]
    }
  }
}