@skvil/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skvil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+<div align="center">
+
+# skvil-mcp
+
+**MCP server for the Skvil security scanner**
+
+Verify, scan, and check on-chain certifications for AI agent skills — directly from your AI assistant.
+
+[![npm version](https://img.shields.io/npm/v/@skvil/mcp-server)](https://www.npmjs.com/package/@skvil/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-8B5CF6)](https://modelcontextprotocol.io)
+
+</div>
+
+---
+
+## Why skvil-mcp?
+
+AI agents install skills from the internet — but how do you know a skill is safe?
+
+Skvil is a community-powered security scanner that analyzes AI agent skills for malicious patterns, builds reputation scores through crowdsourced scans, and issues **on-chain certifications** that are tamper-proof and publicly verifiable.
+
+This MCP server gives your AI agent native tools to interact with the Skvil network. No HTTP knowledge required — just ask your agent to verify a skill.
+
+### On-chain certification
+
+Skvil's certification pipeline is what sets it apart — the entire process is **fully automated with zero human intervention**:
+
+1. **Community scanning** — multiple independent agents scan the same skill
+2. **Reputation building** — scores aggregate via exponential moving average (EMA)
+3. **Crucible analysis** — automated static analysis scans 32+ pattern categories, then an AI triage phase (embeddings + LLM) validates findings and filters false positives
+4. **On-chain registration** — skills scoring ≥ 80 are automatically anchored on Solana via SPL Memo transactions, creating a tamper-proof trust anchor that no single party can forge or revoke silently
+
+Certification is algorithmic: score ≥ 50 passes, score < 50 fails and revokes any existing certificate. A periodic re-certification scheduler re-analyzes certified skills and revokes those that no longer pass.
+
+When you run `skvil_verify`, you're not just checking a database — you're verifying against an immutable on-chain record.
+
+---
+
+## Quick start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skvil": {
+      "command": "npx",
+      "args": ["-y", "@skvil/mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "skvil": {
+      "command": "npx",
+      "args": ["-y", "@skvil/mcp-server"]
+    }
+  }
+}
+```
+
+### VS Code / Cursor
+
+Add to your settings (JSON):
+
+```json
+{
+  "mcp.servers": {
+    "skvil": {
+      "command": "npx",
+      "args": ["-y", "@skvil/mcp-server"]
+    }
+  }
+}
+```
+
+That's it. The server auto-registers a free API key on first use. Zero config.
+
+---
+
+## Tools
+
+| Tool | Auth | Description |
+|------|------|-------------|
+| `skvil_verify` | No | Check if a skill is safe by its SHA-256 hash. Returns reputation score, risk level, on-chain certification status, and Crucible behavioral analysis. |
+| `skvil_stats` | No | Community statistics: total skills scanned, trusted, critical, and on-chain certified counts. |
+| `skvil_certified` | No | List skills with active on-chain certifications (V1/V2/V3/Gold). Up to 10 most recent. |
+| `skvil_register` | No | Get a free API key (500 scans/day). Auto-cached locally for future use. |
+| `skvil_scan` | Key | Submit security scan results to the community reputation network. |
+| `skvil_report` | Key | Report a suspicious skill. Confirmed reports trigger automatic on-chain revocation. |
+
+### Certification levels
+
+| Level | Meaning |
+|-------|---------|
+| **V1** | Basic verification — scanned by community, passed automated static analysis (32+ pattern categories + AI triage) |
+| **V2** | Enhanced verification — V1 + passed Crucible behavioral analysis in sandboxed environment |
+| **V3** | Full verification — V2 + passed periodic re-certification cycles |
+| **Gold** | Highest trust — V3 + continuous monitoring, reserved for critical infrastructure skills |
+
+All levels are registered on-chain. The entire certification process is automated — no human review is involved at any level. Higher levels require progressively more rigorous automated verification.
+
+---
+
+## Configuration
+
+### API key
+
+The server automatically registers a free API key on first use and caches it in `~/.skvil/mcp-config.json`.
+
+To use an existing key:
+
+```json
+{
+  "mcpServers": {
+    "skvil": {
+      "command": "npx",
+      "args": ["-y", "@skvil/mcp-server"],
+      "env": {
+        "SKVIL_API_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Custom API URL
+
+For self-hosted or development instances:
+
+```json
+{
+  "env": {
+    "SKVIL_API_URL": "http://localhost:8000"
+  }
+}
+```
+
+### Key resolution order
+
+1. `SKVIL_API_KEY` environment variable
+2. Cached key in `~/.skvil/mcp-config.json`
+3. Legacy Python client key in `~/.skvil/config`
+
+---
+
+## Examples
+
+### "Is this skill safe to install?"
+
+```
+User: Check if sha256:4a2f...c81e is safe
+
+Agent calls skvil_verify → gets reputation, certification, findings
+
+Agent: This skill has a reputation score of 91.2 (safe) and is
+       on-chain certified at V2 level. 15 community scans with
+       no critical findings. Safe to install.
+```
+
+### "What skills are certified?"
+
+```
+User: Show me certified skills
+
+Agent calls skvil_certified → gets list of on-chain certified skills
+
+Agent: There are 7 on-chain certified skills:
+       1. web-scraper — V2, score 91.2, certified Feb 18
+       2. data-pipeline — V1, score 85.0, certified Feb 15
+       ...
+```
+
+### "Report this suspicious skill"
+
+```
+User: Report sha256:dead...beef — it's sending data to an unknown server
+
+Agent calls skvil_report → submits report
+
+Agent: Report #42 submitted. The skill will be re-analyzed
+       automatically. If the report is confirmed, the skill
+       will be flagged and any on-chain certification will
+       be revoked.
+```
+
+---
+
+## How it works
+
+```
+┌─────────────┐     stdio      ┌────────────┐     HTTPS     ┌──────────────────┐
+│  AI Agent   │ ◄────────────► │  skvil-mcp │ ────────────► │  api.skvil.com   │
+│  (Claude,   │    MCP tools   │  (local)   │   REST API    │  (reputation DB  │
+│   GPT, etc) │                │            │               │   + on-chain)    │
+└─────────────┘                └────────────┘               └──────────────────┘
+```
+
+The MCP server runs locally as a subprocess of your AI client. It translates MCP tool calls into HTTPS requests to the Skvil API. No data is stored remotely except scan results and reports — and certifications are anchored on-chain for public verification.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Skvil-IA/skvil-mcp.git
+cd skvil-mcp
+npm install
+npm run build
+```
+
+### Run locally
+
+```bash
+# Point to local API for development
+SKVIL_API_URL=http://localhost:8000 node dist/index.js
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+### Lint & format
+
+```bash
+npm run lint
+npm run format
+npm run typecheck
+```
+
+---
+
+## License
+
+[MIT](LICENSE) — Skvil 2026

package/dist/api.js

@@ -0,0 +1,123 @@
+import { getApiKey, getBaseUrl, saveApiKey } from './config.js';
+import { VERSION } from './version.js';
+const USER_AGENT = `skvil-mcp/${VERSION}`;
+const TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_048_576; // 1 MB
+const RETRIABLE_STATUSES = new Set([502, 503, 504]);
+const MAX_RETRIES = 2;
+const BASE_DELAY_MS = 1_000;
+export class SkvilApiError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`HTTP ${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.name = 'SkvilApiError';
+    }
+}
+async function request(method, path, options = {}) {
+    const url = `${getBaseUrl()}${path}`;
+    const headers = {
+        'User-Agent': USER_AGENT,
+        Accept: 'application/json',
+    };
+    if (options.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+    }
+    if (options.auth) {
+        const key = getApiKey();
+        if (!key) {
+            throw new SkvilApiError(401, 'No API key configured. Use skvil_register to get one, or set SKVIL_API_KEY env var.');
+        }
+        headers['X-API-Key'] = key;
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        if (attempt > 0) {
+            const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+            // Guard against excessively large responses
+            const contentLength = parseInt(response.headers.get('content-length') || '0', 10);
+            if (contentLength > MAX_RESPONSE_BYTES) {
+                throw new SkvilApiError(502, 'Response too large');
+            }
+            const text = await response.text();
+            if (!response.ok) {
+                // Retry on transient server errors (not on 4xx client errors)
+                if (RETRIABLE_STATUSES.has(response.status) && attempt < MAX_RETRIES) {
+                    lastError = new SkvilApiError(response.status, text.slice(0, 200));
+                    continue;
+                }
+                let detail = text.slice(0, 500);
+                try {
+                    const parsed = JSON.parse(text);
+                    detail = parsed.detail || detail;
+                }
+                catch {
+                    // Use raw text
+                }
+                throw new SkvilApiError(response.status, detail);
+            }
+            return JSON.parse(text);
+        }
+        catch (error) {
+            // Retry on network errors (AbortError = timeout, TypeError = DNS/connection)
+            if (error instanceof Error &&
+                (error.name === 'AbortError' || error.name === 'TypeError') &&
+                attempt < MAX_RETRIES) {
+                lastError = error;
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // All retries exhausted
+    throw lastError;
+}
+/** Check if a skill is safe by its composite hash. */
+export async function verify(hash) {
+    return request('GET', `/verify/${encodeURIComponent(hash)}`);
+}
+/** Get community statistics. */
+export async function stats() {
+    return request('GET', '/stats');
+}
+/** List actively certified skills. */
+export async function certified() {
+    return request('GET', '/certified');
+}
+/** List all certified skills with full catalog metadata. */
+export async function catalog() {
+    return request('GET', '/catalog');
+}
+/** Register for a free API key and cache it locally. */
+export async function register() {
+    const result = await request('POST', '/register');
+    saveApiKey(result.api_key, result.key_prefix);
+    return result;
+}
+/** Submit scan results for a skill. */
+export async function scan(payload) {
+    return request('POST', '/scan', { body: payload, auth: true });
+}
+/** Report a suspicious skill. */
+export async function report(hash, reason, details) {
+    const body = { composite_hash: hash, reason };
+    if (details !== undefined)
+        body.details = details;
+    return request('POST', '/report', { body, auth: true });
+}

package/dist/config.js

@@ -0,0 +1,102 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const CONFIG_DIR = join(homedir(), '.skvil');
+const CONFIG_FILE = join(CONFIG_DIR, 'mcp-config.json');
+/** In-memory cache to avoid repeated disk reads. */
+let cachedApiKey;
+let cachedBaseUrl;
+function readConfig() {
+    try {
+        if (!existsSync(CONFIG_FILE))
+            return {};
+        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+/**
+ * Resolve the API key from (in priority order):
+ * 1. SKVIL_API_KEY or SKVIL_KEDAVRA_API_KEY environment variable
+ * 2. Cached key in ~/.skvil/mcp-config.json
+ * 3. Legacy Python client config at ~/.skvil/config
+ *
+ * Result is memoized for the lifetime of the process.
+ */
+export function getApiKey() {
+    if (cachedApiKey !== undefined)
+        return cachedApiKey;
+    const envKey = process.env.SKVIL_API_KEY || process.env.SKVIL_KEDAVRA_API_KEY;
+    if (envKey) {
+        cachedApiKey = envKey;
+        return cachedApiKey;
+    }
+    const config = readConfig();
+    if (config.api_key) {
+        cachedApiKey = config.api_key;
+        return cachedApiKey;
+    }
+    // Try legacy Python client config (key=value format)
+    try {
+        const legacyPath = join(homedir(), '.skvil', 'config');
+        if (existsSync(legacyPath)) {
+            const content = readFileSync(legacyPath, 'utf-8');
+            const match = content.match(/^api_key\s*=\s*(.+)$/m);
+            if (match) {
+                const key = match[1].trim();
+                if (/^[a-zA-Z0-9_-]+$/.test(key)) {
+                    cachedApiKey = key;
+                    return cachedApiKey;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    cachedApiKey = null;
+    return null;
+}
+/** Cache a newly registered API key for future use. */
+export function saveApiKey(apiKey, keyPrefix) {
+    const config = readConfig();
+    config.api_key = apiKey;
+    config.key_prefix = keyPrefix;
+    config.registered_at = new Date().toISOString();
+    writeConfig(config);
+    cachedApiKey = apiKey;
+}
+/** Clear the memoized API key (used after registration). */
+export function clearApiKeyCache() {
+    cachedApiKey = undefined;
+}
+/**
+ * Get the API base URL (override with SKVIL_API_URL or SKVIL_KEDAVRA_API_URL).
+ * Enforces HTTPS for non-localhost URLs to prevent credential leakage.
+ * Result is memoized for the lifetime of the process.
+ */
+export function getBaseUrl() {
+    if (cachedBaseUrl !== undefined)
+        return cachedBaseUrl;
+    const override = process.env.SKVIL_API_URL || process.env.SKVIL_KEDAVRA_API_URL;
+    if (override) {
+        const isLocalhost = /^https?:\/\/(localhost|127\.0\.0\.1|::1)(:\d+)?/.test(override);
+        if (!override.startsWith('https://') && !isLocalhost) {
+            process.stderr.write('[skvil-mcp] WARNING: SKVIL_API_URL must use HTTPS. Falling back to api.skvil.com.\n');
+            cachedBaseUrl = 'https://api.skvil.com';
+        }
+        else {
+            cachedBaseUrl = override.replace(/\/+$/, '');
+        }
+    }
+    else {
+        cachedBaseUrl = 'https://api.skvil.com';
+    }
+    return cachedBaseUrl;
+}

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.js';
+import { VERSION } from './version.js';
+process.on('unhandledRejection', (err) => {
+    process.stderr.write(`[skvil-mcp] unhandled rejection: ${err}\n`);
+    process.exit(1);
+});
+const server = new McpServer({
+    name: 'skvil',
+    version: VERSION,
+});
+registerTools(server);
+try {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[skvil-mcp] failed to start: ${message}\n`);
+    process.exit(1);
+}

package/dist/tools.js

@@ -0,0 +1,351 @@
+import { z } from 'zod';
+import * as api from './api.js';
+import { getApiKey } from './config.js';
+const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const hashSchema = z
+    .string()
+    .regex(HASH_PATTERN, 'Must be "sha256:" followed by 64 hex characters')
+    .describe('SHA-256 composite hash of the skill (e.g. "sha256:4a2f8b...c81e")');
+function formatScore(score) {
+    if (score >= 80)
+        return `${score.toFixed(1)} (safe)`;
+    if (score >= 50)
+        return `${score.toFixed(1)} (caution)`;
+    return `${score.toFixed(1)} (danger)`;
+}
+/** Register all skvil tools on the MCP server. */
+export function registerTools(server) {
+    // ── skvil_verify ──────────────────────────────────────────────────────────
+    server.tool('skvil_verify', 'Check if an AI agent skill is safe before installing it. Returns reputation ' +
+        'score, risk level, certification status, and community scan data. ' +
+        'Use this to verify any skill by its SHA-256 composite hash.', { hash: hashSchema }, async ({ hash }) => {
+        try {
+            const result = await api.verify(hash);
+            if (!result.known) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `**Unknown skill** (${hash})\n\n` +
+                                'This skill has never been scanned by the Skvil network.\n' +
+                                'It has no reputation data or certification.\n\n' +
+                                '**Recommendation:** Do not install without scanning first.',
+                        },
+                    ],
+                };
+            }
+            const score = result.reputation_score ?? 0;
+            const totalScans = result.total_scans ?? 0;
+            const lines = [
+                `**Skill verification: ${hash}**\n`,
+                `- **Reputation score:** ${formatScore(score)}`,
+                `- **Total community scans:** ${totalScans}`,
+                `- **Risk level:** ${result.risk_summary?.last_risk_level ?? 'unknown'}`,
+            ];
+            if (result.certification) {
+                lines.push(`- **Certification:** ${result.certification}`);
+            }
+            else {
+                lines.push('- **Certification:** none');
+            }
+            if (result.confirmed_malicious) {
+                lines.push('\n**CONFIRMED MALICIOUS** — a Skvil admin has verified this skill is dangerous.');
+                lines.push('Do NOT install this skill.');
+            }
+            if (result.risk_summary) {
+                const f = result.risk_summary.findings_by_severity;
+                const critical = f.critical ?? 0;
+                const high = f.high ?? 0;
+                const medium = f.medium ?? 0;
+                const low = f.low ?? 0;
+                if (critical > 0 || high > 0) {
+                    lines.push(`\n**Findings:** ${critical} critical, ${high} high, ${medium} medium, ${low} low`);
+                }
+            }
+            if (result.crucible) {
+                lines.push(`\n**Crucible behavioral analysis:** ${result.crucible.status}`);
+                lines.push(`- Behavioral score: ${result.crucible.score}`);
+                if (result.crucible.behavioral_findings.length > 0) {
+                    const descriptions = result.crucible.behavioral_findings
+                        .map((f) => f.description)
+                        .join(', ');
+                    lines.push(`- Findings: ${descriptions}`);
+                }
+            }
+            // Decision recommendation
+            lines.push('\n**Recommendation:**');
+            if (result.confirmed_malicious) {
+                lines.push('Do NOT install. This skill has been confirmed malicious.');
+            }
+            else if (result.crucible?.status === 'malicious') {
+                lines.push('Do NOT install. Behavioral analysis detected malicious activity.');
+            }
+            else if (score >= 80 && result.certification) {
+                lines.push(`Safe to install. This skill is certified (${result.certification}) ` +
+                    'with a strong reputation score.');
+            }
+            else if (score >= 60) {
+                lines.push('Likely safe, but not yet certified. Install with caution.');
+            }
+            else if (score < 40) {
+                lines.push('Do NOT install. Low reputation score indicates potential risk.');
+            }
+            else {
+                lines.push('Proceed with caution. Review findings before installing.');
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (error) {
+            return { content: [{ type: 'text', text: formatError('verify', error) }], isError: true };
+        }
+    });
+    // ── skvil_stats ───────────────────────────────────────────────────────────
+    server.tool('skvil_stats', 'Get aggregate statistics from the Skvil community network: total skills ' +
+        'scanned, trusted count, critical findings, and certified skills.', {}, async () => {
+        try {
+            const result = await api.stats();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: '**Skvil community statistics**\n\n' +
+                            `- **Total skills scanned:** ${result.total}\n` +
+                            `- **Trusted** (reputation >= 70): ${result.trusted}\n` +
+                            `- **Critical findings:** ${result.critical}\n` +
+                            `- **Certified:** ${result.certified}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: 'text', text: formatError('stats', error) }], isError: true };
+        }
+    });
+    // ── skvil_certified ───────────────────────────────────────────────────────
+    server.tool('skvil_certified', 'List skills that have been verified and certified by Skvil admins. ' +
+        'Certified skills have been manually reviewed and registered for ' +
+        'tamper-proof verification. Returns up to 10 most recently certified ' +
+        'skills with their level (V1/V2/V3/Gold), reputation score, and ' +
+        'certification date.', {}, async () => {
+        try {
+            const result = await api.certified();
+            if (result.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'No skills are currently certified. Be the first to get certified!',
+                        },
+                    ],
+                };
+            }
+            const lines = ['**Certified skills**\n'];
+            for (const skill of result) {
+                lines.push(`- **${skill.name}** — ${skill.level} | Score: ${formatScore(skill.reputation_score)} | ` +
+                    `${skill.total_scans} scans | Certified: ${skill.certified_at}\n` +
+                    `  Hash: \`${skill.composite_hash}\``);
+            }
+            lines.push('\nAll certifications are registered for tamper-proof, publicly verifiable trust.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError('certified', error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── skvil_catalog ──────────────────────────────────────────────────────────
+    server.tool('skvil_catalog', 'Browse the full catalog of Skvil-certified AI agent skills with detailed ' +
+        'metadata: author, version, description, provider, agent platform, file ' +
+        'count, and install URL. Returns up to 100 skills. Use this to discover ' +
+        'safe skills available for installation.', {}, async () => {
+        try {
+            const result = await api.catalog();
+            if (result.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'The skill catalog is empty. No certified skills available yet.',
+                        },
+                    ],
+                };
+            }
+            const lines = [`**Skvil skill catalog** (${result.length} certified skills)\n`];
+            for (const skill of result) {
+                const parts = [`- **${skill.name}**`];
+                parts.push(`  Level: ${skill.level} | Score: ${formatScore(skill.reputation_score)} | ${skill.total_scans} scans`);
+                if (skill.author)
+                    parts.push(`  Author: ${skill.author}`);
+                if (skill.version)
+                    parts.push(`  Version: ${skill.version}`);
+                if (skill.description)
+                    parts.push(`  ${skill.description}`);
+                if (skill.provider)
+                    parts.push(`  Provider: ${skill.provider}`);
+                if (skill.agent)
+                    parts.push(`  Agent: ${skill.agent}`);
+                parts.push(`  Files: ${skill.file_count} | Certified: ${skill.certified_at}`);
+                if (skill.skill_url)
+                    parts.push(`  Install: ${skill.skill_url}`);
+                parts.push(`  Hash: \`${skill.composite_hash}\``);
+                lines.push(parts.join('\n'));
+            }
+            return { content: [{ type: 'text', text: lines.join('\n\n') }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError('catalog', error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── skvil_register ────────────────────────────────────────────────────────
+    server.tool('skvil_register', 'Register for a free Skvil API key. The key is automatically cached ' +
+        'locally for future use. No sign-up or account required. Other tools ' +
+        '(skvil_scan, skvil_report) will use the cached key automatically.', {}, async () => {
+        try {
+            const existing = getApiKey();
+            if (existing) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'An API key is already configured.\n\n' +
+                                'To register a new key, unset the `SKVIL_API_KEY` env var and ' +
+                                'delete `~/.skvil/mcp-config.json`, then try again.',
+                        },
+                    ],
+                };
+            }
+            const result = await api.register();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: '**API key registered successfully!**\n\n' +
+                            `- **Key prefix:** ${result.key_prefix}...\n` +
+                            `- **Tier:** ${result.tier}\n\n` +
+                            'The key has been cached in `~/.skvil/mcp-config.json`.\n' +
+                            'You can now use `skvil_scan` and `skvil_report`.',
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatError('register', error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── skvil_report ──────────────────────────────────────────────────────────
+    server.tool('skvil_report', 'Report a suspicious or malicious AI agent skill to Skvil admins for review. ' +
+        'Requires an API key (use skvil_register first). Reports are reviewed by ' +
+        'admins and confirmed findings lead to certification revocation.', {
+        hash: hashSchema,
+        reason: z
+            .string()
+            .min(10)
+            .max(1000)
+            .describe('Why this skill is suspicious (10-1000 characters)'),
+        details: z
+            .string()
+            .max(5000)
+            .optional()
+            .describe('Additional details or evidence (optional, max 5000 characters)'),
+    }, async ({ hash, reason, details }) => {
+        try {
+            const result = await api.report(hash, reason, details);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: '**Report submitted successfully**\n\n' +
+                            `- **Report ID:** ${result.report_id}\n` +
+                            `- **Status:** ${result.status}\n` +
+                            `- **Skill hash:** ${hash}\n\n` +
+                            'A Skvil admin will review this report. If confirmed, the skill ' +
+                            'will be flagged as malicious and any existing certification ' +
+                            'will be revoked.',
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: 'text', text: formatError('report', error) }], isError: true };
+        }
+    });
+    // ── skvil_scan ────────────────────────────────────────────────────────────
+    server.tool('skvil_scan', 'Submit security scan results for an AI agent skill to the Skvil reputation ' +
+        'network. Contributes to the community reputation score (EMA). Requires an ' +
+        'API key (use skvil_register first). The server recomputes the score from ' +
+        'findings — always provide accurate findings.', {
+        name: z.string().max(256).describe('Skill name'),
+        composite_hash: hashSchema,
+        file_count: z.number().int().min(0).max(10000).describe('Number of files in the skill'),
+        file_hashes: z
+            .record(z
+            .string()
+            .max(500)
+            .regex(/^[a-zA-Z0-9_\-./]+$/, 'Invalid file path'), z.string().regex(/^[a-f0-9]{64}$/, 'Must be 64 hex characters'))
+            .describe('Map of relative file paths to their SHA-256 hex hashes'),
+        score: z.number().int().min(0).max(100).describe('Computed security score (0-100)'),
+        risk_level: z.enum(['safe', 'caution', 'danger']).describe('Overall risk assessment'),
+        findings: z
+            .array(z.object({
+            severity: z.enum(['critical', 'high', 'medium', 'low']),
+            category: z.string().max(100),
+            description: z.string().max(1000),
+            file: z.string().max(500),
+            line: z.number().int().optional(),
+        }))
+            .max(500)
+            .default([])
+            .describe('Security findings detected in the skill'),
+        frontmatter: z
+            .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+            .optional()
+            .describe('SKILL.md frontmatter metadata (optional)'),
+    }, async (params) => {
+        try {
+            const result = await api.scan(params);
+            const lines = [
+                '**Scan submitted successfully**\n',
+                `- **Scan ID:** ${result.scan_id}`,
+                `- **Updated reputation:** ${formatScore(result.reputation_score)}`,
+                `- **Total community scans:** ${result.total_scans}`,
+            ];
+            if (result.certification) {
+                lines.push(`- **Certification:** ${result.certification}`);
+            }
+            lines.push('\nYour scan contributes to the community reputation via exponential ' +
+                'moving average (EMA). Thank you for helping secure the AI skill ecosystem.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (error) {
+            return { content: [{ type: 'text', text: formatError('scan', error) }], isError: true };
+        }
+    });
+}
+function formatError(tool, error) {
+    if (error instanceof api.SkvilApiError) {
+        if (error.status === 429) {
+            return `**Rate limit exceeded** — ${error.detail}\nTry again later.`;
+        }
+        if (error.status === 401) {
+            return (`**Authentication required** — ${error.detail}\n` +
+                'Use `skvil_register` to get a free API key.');
+        }
+        const safeDetail = error.detail.slice(0, 500);
+        return `**Error in skvil_${tool}** (HTTP ${error.status})\n${safeDetail}`;
+    }
+    if (error instanceof Error) {
+        if (error.name === 'AbortError' || error.name === 'TimeoutError') {
+            return '**Timeout** — the Skvil API did not respond in time. Try again.';
+        }
+        return `**Error in skvil_${tool}**\n${error.message}`;
+    }
+    return `**Unexpected error in skvil_${tool}**\n${String(error)}`;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Skvil API response types. */
+export {};

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Single source of truth for the package version. */
+export const VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@skvil/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for the Skvil security scanner — verify, scan, and report AI agent skills",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "skvil-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "lint": "eslint src/",
+    "format": "prettier --write 'src/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'No tests configured yet' && exit 0",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "skvil",
+    "security",
+    "ai-agents",
+    "ai-skills",
+    "scanner"
+  ],
+  "author": "Skvil <terminal@skvil.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Skvil-IA/skvil-mcp.git"
+  },
+  "homepage": "https://skvil.com",
+  "bugs": {
+    "url": "https://github.com/Skvil-IA/skvil-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "eslint": "^9.0.0",
+    "@eslint/js": "^9.0.0",
+    "typescript-eslint": "^8.0.0",
+    "prettier": "^3.4.0"
+  }
+}