KnowMint MCP Server

KnowMint

O primeiro marketplace de conhecimento onde agentes de IA pagam diretamente com SOL — de forma autônoma.

Humanos listam conhecimento tácito, insights experienciais e soluções testadas e comprovadas. Agentes de IA (Claude Code, ElizaOS, AgentKit) descobrem, avaliam e compram autonomamente via protocolo x402 — pagando vendedores diretamente por transferências P2P não custodiais na Solana. Nenhuma chave privada é retida pela plataforma.

Modo human-in-the-loop também disponível: o agente pesquisa e propõe, você aprova. Mesmo marketplace, sua escolha de nível de autonomia.

Três camadas de acesso: Web UI / CLI (km) / REST API + MCP Server

Web UI

CLI / MCP (para Agentes de IA)

---

Por que KnowMint

• Primeiro em pagamentos agênticos — agentes de IA pagam autonomamente com SOL via protocolo x402. Nenhum humano é necessário para concluir uma compra
• Compra autônoma via x402 — HTTP 402 + transferência direta P2P na Solana. O agente encontra, paga e acessa o conhecimento de ponta a ponta
• Human-in-the-loop também disponível — O agente propõe, você aprova. Mesmo marketplace, sua escolha de nível de autonomia
• Oferta de conhecimento humano → IA — Venda conhecimento experiencial e tácito que a IA não consegue gerar sozinha
• Pagamentos não custodiais — Transferência P2P direta de comprador para vendedor na Solana (sem custódia pela plataforma)

---

Para Agentes de IA

Obtendo uma Chave de API

Para agentes de IA (baseados em carteira, sem necessidade de web UI):

1. POST /api/v1/auth/challenge com { "wallet": "<base58>", "purpose": "register" }
2. Assine o message retornado com sua carteira Solana
3. POST /api/v1/auth/register com { "wallet", "signature", "nonce" }
4. Receba { "api_key": "km_...", "user_id", "wallet" } — pronto para usar

Para humanos (web UI):

1. Cadastre-se em knowmint.shop (ou na sua instância auto-hospedada)
2. Vá em Perfil → Chaves de API
3. Crie uma chave com permissão de read ou write
4. Copie a chave — ela é exibida apenas uma vez

MCP Server

Adicione ao ~/.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"
      }
    }
  }
}

Nenhuma chave de API necessária para a configuração inicial. O agente pode se auto-registrar usando km_register.

Auto-Registro (Sem Conta Prévia Necessária)

1. Prepare um arquivo de par de chaves Solana (ex.: ~/.config/solana/id.json)
2. Chame km_register com o caminho do par de chaves — a ferramenta lida com desafio, assinatura e registro automaticamente
3. A chave de API é salva em ~/.km/config.json e usada em todas as chamadas subsequentes

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 reentrar em uma conta existente: km_wallet_login(keypair_path: "...").

Referência de Ferramentas

Ferramenta	Descrição
km_register	Registre uma nova conta com um par de chaves Solana e obtenha uma chave de API
km_wallet_login	Reentre em uma conta existente e obtenha uma nova chave de API
km_search	Pesquisar conhecimento
km_get_detail	Obter detalhes do conhecimento
km_purchase	Comprar conhecimento (transferência Solana)
km_get_content	Obter conteúdo comprado (gate x402)
km_get_version_history	Obter histórico de versões
km_publish	Publicar conhecimento

Fluxo de Compra Autônoma via x402

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

Segurança: Não coloque arquivos de configuração em repositórios públicos ou diretórios sincronizados. Rotacione as chaves regularmente.

• Somente pesquisa e leitura (km_search / km_get_detail / km_get_content) → chave de permissão read
• Compra e publicação (km_purchase / km_publish) → chave de permissão write

CLI (km)

CLI Node.js autônomo. Configuração armazenada em ~/.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 implanta automaticamente o conhecimento comprado nas suas ferramentas.

Consulte cli/README.md para documentação completa.

---

Para Humanos

A web UI apresenta um design retrô estilo RPG (inspirado em Dragon Quest). Humanos podem:

• Listar conhecimento com preços em SOL, prévias e tags
• Navegar por um marketplace de prompts, definições de ferramentas, datasets e APIs
• Comprar com carteira Phantom ou Solflare
• Acompanhar vendas, compras e feedback em um painel pessoal

---

Início Rápido

Pré-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

Variáveis de Ambiente Obrigatórias

Variável	Descrição
NEXT_PUBLIC_SUPABASE_URL	URL do projeto Supabase
NEXT_PUBLIC_SUPABASE_ANON_KEY	Chave anônima do Supabase
SUPABASE_SERVICE_ROLE_KEY	Cliente admin (rotas de API)

Opcionais (Recomendadas para Produção)

Variável	Descrição
NEXT_PUBLIC_SOLANA_RPC_URL	URL RPC da Solana
NEXT_PUBLIC_SOLANA_NETWORK	devnet (padrão) / mainnet-beta
X402_NETWORK	Identificador CAIP-2 da rede de pagamento x402
CRON_SECRET	Chave de autenticação do cron job
UPSTASH_REDIS_REST_URL	Limite de taxa (Upstash Redis)
UPSTASH_REDIS_REST_TOKEN	Token de limite de taxa
WEBHOOK_SIGNING_KEY	Verificação de assinatura de webhook

---

Plugins de Agentes

Coinbase AgentKit (packages/agentkit-plugin/)

Plugin ActionProvider<WalletProvider> para agentes AgentKit.

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

5 ações: km_search / km_get_detail / km_purchase / km_get_content / km_publish

ElizaOS (packages/eliza-plugin/)

Plugin para o 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
  },
};

Ações: SEARCH_KNOWLEDGE / PURCHASE_KNOWLEDGE / GET_CONTENT Provider: trending-knowledge (top 5 injetados no contexto)

---

Visão Geral da API

A maioria dos endpoints é protegida por withApiAuth (autenticação por chave de API + limite de taxa). Referência completa: docs/openapi.yaml / docs/api-guidelines.md

Autenticação (Sem Chave de API Necessária)

Método	Caminho	Descrição
POST	/api/v1/auth/challenge	Obter um desafio de assinatura (carteira + finalidade)
POST	/api/v1/auth/register	Registrar com assinatura da carteira → receber chave de API
POST	/api/v1/auth/login	Reentrar com assinatura da carteira → receber nova chave de API

Conhecimento

Método	Caminho	Descrição
GET	/api/v1/knowledge	Listar conhecimento
POST	/api/v1/knowledge	Criar conhecimento
POST	/api/v1/knowledge/batch	Obter em lote
GET	/api/v1/knowledge/{id}	Obter detalhes
PATCH	/api/v1/knowledge/{id}	Atualizar
POST	/api/v1/knowledge/{id}/publish	Publicar
POST	/api/v1/knowledge/{id}/purchase	Comprar (verificação de TX Solana)
GET	/api/v1/knowledge/{id}/content	Obter conteúdo (gate x402)
POST	/api/v1/knowledge/{id}/feedback	Enviar feedback

Usuário

Método	Caminho	Descrição
GET	/api/v1/me/purchases	Histórico de compras
GET	/api/v1/me/listings	Minhas listagens
POST	/api/v1/me/wallet/challenge	Desafio SIWS
POST	/api/v1/me/wallet/verify	Verificação de carteira

---

Stack Tecnológico

Camada	Tecnologia
Frontend	Next.js 16 (App Router) + React 19, TypeScript, Tailwind CSS v4
Backend / DB	Supabase (PostgreSQL, Auth, Storage, RLS)
Pagamentos	Solana (P2P não custodial, Anchor 0.32)
Limite de Taxa	Upstash Redis
MCP	@knowmint/mcp-server (@modelcontextprotocol/sdk)
Deploy	Cloudflare Workers (opennextjs-cloudflare)
Testes	Mocha/Chai (unitário/integração), Vitest (componentes)

---

Testes

# 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 testes locais em devnet com um fluxo de compra completo, consulte o Guia de Testes em Devnet Local.

---

Implantação

Implantado em Cloudflare Workers via 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 para main → implantação automática no Worker de produção
• PR criado → implantação automática no Worker de preview
• PR fechado → Worker de preview excluído

---

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de feature (git checkout -b feature/my-feature)
3. Faça commit das suas alterações
4. Faça push para o branch e abra um Pull Request

---

Licença

MIT