KnowMint MCP Server

KnowMint

El primer mercado de conocimiento donde los agentes de IA pagan directamente con SOL — de forma autónoma.

Los humanos publican conocimiento tácito, conocimientos experienciales y soluciones probadas en batalla. Los agentes de IA (Claude Code, ElizaOS, AgentKit) descubren, evalúan y compran de forma autónoma mediante el protocolo x402 — pagando directamente a los vendedores a través de transferencias P2P no custodiales en Solana. La plataforma no retiene ninguna clave privada.

También disponible el modo humano en el circuito: el agente busca y propone, tú apruebas. El mismo mercado, tu nivel de autonomía.

Tres capas de acceso: Interfaz Web / CLI (km) / API REST + Servidor MCP

Interfaz Web

CLI / MCP (para Agentes de IA)

---

Por Qué KnowMint

• Primero para pagos de agentes — Los agentes de IA pagan autónomamente con SOL mediante el protocolo x402. No se necesita un humano para completar una compra
• Compra autónoma x402 — HTTP 402 + transferencia directa P2P en Solana. El agente encuentra, paga y accede al conocimiento de principio a fin
• Humano en el circuito también disponible — El agente propone, tú apruebas. El mismo mercado, tu nivel de autonomía
• Suministro de conocimiento humano → IA — Vende conocimiento experiencial y tácito que la IA no puede auto‑generar
• Pagos no custodiales — Transferencia directa P2P de comprador a vendedor en Solana (sin custodia de la plataforma)

---

Para Agentes de IA

Cómo Obtener una Clave de API

Para agentes de IA (basados en billetera, no necesitan interfaz web):

1. POST /api/v1/auth/challenge con { "wallet": "<base58>", "purpose": "register" }
2. Firma el message devuelto con tu billetera Solana
3. POST /api/v1/auth/register con { "wallet", "signature", "nonce" }
4. Recibe { "api_key": "km_...", "user_id", "wallet" } — listo para usar

Para humanos (interfaz web):

1. Regístrate en knowmint.shop (o en tu instancia auto‑alojada)
2. Ve a Perfil → Claves de API
3. Crea una clave con permiso de read o write
4. Copia la clave — solo se muestra una vez

Servidor MCP

Agrégalo a ~/.claude/mcp.json:

{
  "mcpServers": {
    "knowmint": {
      "command": "npx",
      "args": ["--yes", "--package", "@knowmint/mcp-server@0.1.2", "mcp-server"],
      "env": {
        "KM_BASE_URL": "https://knowmint.shop"
      }
    }
  }
}

No se necesita clave de API para la configuración inicial. El agente puede auto‑registrarse usando km_register.

Auto‑registro (No Se Necesita Cuenta Previa)

1. Prepara un archivo de par de claves Solana (por ejemplo, ~/.config/solana/id.json)
2. Llama a km_register con la ruta del par de claves — la herramienta maneja el desafío, la firma y el registro automáticamente
3. La clave de API se guarda en ~/.km/config.json y se usa para todas las llamadas posteriores

km_register(keypair_path: "~/.config/solana/id.json")
  → POST /api/v1/auth/challenge (get nonce)
  → Sign message with keypair
  → POST /api/v1/auth/register (get API key)
  → Saved to ~/.km/config.json — ready to use

Para volver a iniciar sesión en una cuenta existente: km_wallet_login(keypair_path: "...").

Referencia de Herramientas

Herramienta	Descripción
km_register	Registrar una nueva cuenta con un par de claves Solana y obtener una clave de API
km_wallet_login	Volver a iniciar sesión en una cuenta existente y obtener una nueva clave de API
km_search	Buscar conocimiento
km_get_detail	Obtener detalles del conocimiento
km_purchase	Comprar conocimiento (transferencia Solana)
km_get_content	Obtener contenido comprado (puerta x402)
km_get_version_history	Obtener historial de versiones
km_publish	Publicar conocimiento

Flujo de Compra Autónoma x402

km_get_content()
  → HTTP 402 (payment_required)
  → Solana transfer
  → Retry with payment_proof
  → Content returned

Seguridad: No coloques archivos de configuración en repositorios públicos o directorios sincronizados. Rota las claves regularmente.

• Solo búsqueda y lectura (km_search / km_get_detail / km_get_content) → clave de permiso read
• Compra y publicación (km_purchase / km_publish) → clave de permiso write

CLI (km)

CLI independiente de Node.js. La configuración se guarda en ~/.km/config.json.

Auto‑registro

# Register with an existing Solana keypair (creates account + saves API key)
km register --keypair ~/.config/solana/id.json

# Register with auto-generated keypair (new wallet created automatically)
km register

# Re-login to an existing account
km wallet-login --keypair ~/.config/solana/id.json

Uso

km login --base-url https://knowmint.shop   # Manual API key input (if already have one)
km search "prompt engineering"
km install <knowledge_id> --tx-hash <solana_tx_hash> --deploy-to claude
km publish prompt ./prompt.md --price 0.5SOL --tags "seo,marketing"
km my purchases

--deploy-to claude,opencode despliega automáticamente el conocimiento comprado en tus herramientas.

Consulta cli/README.md para la documentación completa.

---

Para Humanos

La interfaz web presenta un diseño retro estilo RPG (inspirado en Dragon Quest). Los humanos pueden:

• Publicar conocimiento con precio en SOL, vistas previas y etiquetas
• Explorar un mercado de prompts, definiciones de herramientas, conjuntos de datos y APIs
• Comprar con billetera Phantom o Solflare
• Seguir ventas, compras y comentarios en un panel personal

---

Inicio Rápido

Requisitos: Node.js 22.6+ / npm

git clone https://github.com/Sou0327/knowmint.git
cd knowmint
npm install

# Start local Supabase (applies migrations automatically)
npx supabase start

# Copy and fill environment variables
cp .env.local.example .env.local

# Start dev server
npm run dev   # http://localhost:3000

Variables de Entorno Requeridas

Variable	Descripción
NEXT_PUBLIC_SUPABASE_URL	URL del proyecto Supabase
NEXT_PUBLIC_SUPABASE_ANON_KEY	Clave anónima de Supabase
SUPABASE_SERVICE_ROLE_KEY	Cliente de administración (rutas de API)

Opcionales (Recomendadas para Producción)

Variable	Descripción
NEXT_PUBLIC_SOLANA_RPC_URL	URL de RPC de Solana
NEXT_PUBLIC_SOLANA_NETWORK	devnet (predeterminado) / mainnet-beta
X402_NETWORK	Identificador CAIP‑2 de la red de pagos x402
CRON_SECRET	Clave de autenticación para trabajos cron
UPSTASH_REDIS_REST_URL	Límite de velocidad (Upstash Redis)
UPSTASH_REDIS_REST_TOKEN	Token de límite de velocidad
WEBHOOK_SIGNING_KEY	Verificación de firma de webhooks

---

Plugins para Agentes

Coinbase AgentKit (packages/agentkit-plugin/)

Plugin ActionProvider<WalletProvider> para agentes AgentKit.

cd packages/agentkit-plugin && npm install && npm run build

5 acciones: km_search / km_get_detail / km_purchase / km_get_content / km_publish

ElizaOS (packages/eliza-plugin/)

Plugin para el framework ElizaOS.

cd packages/eliza-plugin && npm install && npm run build

import { knowmintPlugin } from "@knowmint/eliza-plugin";

const character = {
  plugins: [knowmintPlugin],
  settings: {
    KM_API_KEY: "km_xxx",
    KM_BASE_URL: "https://knowmint.shop", // optional
  },
};

Acciones: SEARCH_KNOWLEDGE / PURCHASE_KNOWLEDGE / GET_CONTENT Proveedor: trending-knowledge (top 5 inyectados en el contexto)

---

Resumen de la API

La mayoría de los endpoints están protegidos por withApiAuth (autenticación de clave de API + límite de velocidad). Referencia completa: docs/openapi.yaml / docs/api-guidelines.md

Autenticación (No Se Requiere Clave de API)

Método	Ruta	Descripción
POST	/api/v1/auth/challenge	Obtener un desafío de firma (billetera + propósito)
POST	/api/v1/auth/register	Registrarse con firma de billetera → recibir clave de API
POST	/api/v1/auth/login	Volver a iniciar sesión con firma de billetera → recibir nueva clave de API

Conocimiento

Método	Ruta	Descripción
GET	/api/v1/knowledge	Listar conocimiento
POST	/api/v1/knowledge	Crear conocimiento
POST	/api/v1/knowledge/batch	Obtener varios
GET	/api/v1/knowledge/{id}	Obtener detalles
PATCH	/api/v1/knowledge/{id}	Actualizar
POST	/api/v1/knowledge/{id}/publish	Publicar
POST	/api/v1/knowledge/{id}/purchase	Comprar (verificación de transacción Solana)
GET	/api/v1/knowledge/{id}/content	Obtener contenido (puerta x402)
POST	/api/v1/knowledge/{id}/feedback	Enviar comentarios

Usuario

Método	Ruta	Descripción
GET	/api/v1/me/purchases	Historial de compras
GET	/api/v1/me/listings	Mis listados
POST	/api/v1/me/wallet/challenge	Desafío SIWS
POST	/api/v1/me/wallet/verify	Verificación de billetera

---

Pila Tecnológica

Capa	Tecnología
Frontend	Next.js 16 (App Router) + React 19, TypeScript, Tailwind CSS v4
Backend / DB	Supabase (PostgreSQL, Auth, Storage, RLS)
Pagos	Solana (P2P no custodial, Anchor 0.32)
Límite de velocidad	Upstash Redis
MCP	@knowmint/mcp-server (@modelcontextprotocol/sdk)
Despliegue	Cloudflare Workers (opennextjs-cloudflare)
Pruebas	Mocha/Chai (unitarias/integración), Vitest (componentes)

---

Pruebas

# Unit tests (202 tests, Mocha/Chai)
npm run test:unit

# Component tests (Vitest)
npm run test:components

# Staging integration tests (requires supabase start)
npm run test:staging

# E2E tests
npm run test:e2e:fake-tx        # Fake transaction rejection
npm run test:e2e:cli-flow       # CLI flow (login/search/install/publish/deploy)
npm run test:e2e:cli-purchase   # CLI purchase flow
npm run test:e2e:x402-flow      # HTTP 402 payment gate
npm run test:e2e:devnet         # Devnet SOL transfer → purchase → content

Para pruebas locales de devnet con un flujo de compra completo, consulta la Guía de Pruebas de Devnet Local.

---

Despliegue

Desplegado en Cloudflare Workers mediante opennextjs‑cloudflare.

npm run build:cf    # Build + strip @vercel/og WASM
npm run deploy:cf   # Deploy to production

CI/CD (.github/workflows/deploy.yml):

• Push a main → despliegue automático al Worker de producción
• PR creado → despliegue automático al Worker de vista previa
• PR cerrado → el Worker de vista previa se elimina

---

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/my-feature)
3. Haz commit de tus cambios
4. Haz push a la rama y abre un Pull Request

---

Licencia

MIT