Configura il server MCP PandaNpc per Claude Code e Codex

Aggiornato

Il server MCP PandaNpc connette un agente di codifica compatibile con MCP alla tua base di conoscenza PandaNote, ai registri di lavoro, alle attività pianificate, alla configurazione dei modelli e all'Agent Service Center. È utile quando un agente ha bisogno di un contesto di progetto duraturo invece di iniziare da una conversazione vuota ogni volta.

Il server viene eseguito localmente tramite il trasporto standard input/output di MCP. Il tuo client MCP avvia il processo pandanpc-mcp quando una sessione si apre; non è necessario esporre una porta o eseguire un server web separato.

Prima di installare

Ti serve:

  • Node.js e npm disponibili nello stesso ambiente in cui gira il client MCP.
  • Un account PandaNpc con accesso all'indirizzo email utilizzato per la verifica.
  • Claude Code, OpenAI Codex, Cursor o un altro client che supporti i server MCP stdio locali.

Se vuoi che l'agente pianifichi il lavoro su uno dei tuoi computer, installa e connetti prima PandaPaw. Gli strumenti di note e workspace non richiedono un dispositivo PandaPaw online.

Installare o aggiornare il server MCP

Installa il pacchetto globalmente su macOS, Linux o Windows:

bash
npm install -g @pandanpc/mcp-server

Conferma che l'eseguibile sia visibile alla tua shell:

bash
pandanpc-mcp --help

Esegui lo stesso comando npm ogni volta che vuoi aggiornare. Riavvia il client MCP dopo un aggiornamento perché un client già in esecuzione mantiene la versione del processo che ha avviato originariamente.

Controlla la cronologia delle versioni del server MCP quando uno strumento o il suo comportamento differisce da uno screenshot o tutorial meno recente.

Aggiungere PandaNpc a Claude Code

Il metodo più affidabile è il comando di configurazione di Claude Code. Usa l'ambito utente se vuoi che PandaNpc sia disponibile in ogni progetto:

bash
claude mcp add --scope user pandanpc -- pandanpc-mcp

Usa invece scope project quando la configurazione deve essere condivisa attraverso il repository corrente, oppure --scope local quando deve applicarsi solo a te nel progetto corrente.

Controlla il server registrato:

bash
claude mcp get pandanpc
claude mcp list

Puoi anche configurare manualmente il server stdio nella configurazione MCP usata dalla tua installazione di Claude Code:

json
{
  "mcpServers": {
    "pandanpc": {
      "command": "pandanpc-mcp"
    }
  }
}

Aggiungere PandaNpc a OpenAI Codex

Codex può registrare lo stesso processo locale dalla riga di comando:

bash
codex mcp add pandanpc -- pandanpc-mcp

Verifica la configurazione salvata:

bash
codex mcp get pandanpc
codex mcp list

La voce equivalente in ~/.codex/config.toml è:

toml
[mcp_servers.pandanpc]
command = "pandanpc-mcp"

Riavvia Codex o apri una nuova sessione dopo aver aggiunto il server. Se mantieni un file di configurazione Codex personalizzato, inserisci la tabella MCP in quel file anziché duplicarla in più file.

Configurare Cursor e altri client MCP

Per Cursor, aggiungi un server locale a ~/.cursor/mcp.json usando la stessa struttura JSON mostrata per Claude Code. Per Windsurf e altri client, crea un server MCP stdio il cui comando sia pandanpc-mcp e la cui lista di argomenti sia vuota.

L'eseguibile deve essere nel PATH ereditato dall'applicazione grafica. Se funziona in un terminale ma il client desktop segnala "comando non trovato", usa il percorso assoluto dell'eseguibile restituito dal seguente comando:

bash
command -v pandanpc-mcp

Su Windows PowerShell, usa:

powershell
Get-Command pandanpc-mcp

Accedi dall'agente

PandaNpc usa un flusso di verifica email in due passaggi. Chiedi all'agente di eseguire queste azioni in ordine:

  1. Chiama note_login con il tuo indirizzo email. PandaNpc invia un codice di verifica.
  2. Chiama di nuovo note_login con lo stesso indirizzo email e il codice.

La credenziale locale viene memorizzata nella cache, quindi non dovresti dover effettuare l'accesso a ogni sessione. Non incollare mai il codice di verifica in una trascrizione pubblica o in un prompt condiviso.

Verificare la connessione MCP

Esegui un piccolo test di sola lettura prima di permettere all'agente di creare o modificare dati:

  1. Chiedigli di chiamare list_workspaces.
  2. Chiedigli di chiamare list_notes per un workspace.
  3. Chiedigli di cercare una parola chiave innocua con search_notes.

Una risposta positiva dimostra che il client MCP ha avviato il processo, l'autenticazione è stata completata e l'API dell'account è raggiungibile. Per un test di scrittura, crea una nota usa e getta e poi eliminala in modo soft.

L'elenco esatto degli strumenti mostrato dal tuo client MCP è la fonte di verità per la versione installata. Gli strumenti sono raggruppati attorno a questi flussi di lavoro:

Flusso di lavoro Strumenti tipici Comportamento importante
Note list_notes, create_note, read_note, update_note, search_notes update_note sostituisce l'intero corpo; leggere prima di modificare
Registri di lavoro save_done Salva automaticamente il lavoro completato nella cartella di progetto di oggi
Workspace list_workspaces, create_workspace, update_workspace Un percorso di progetto associato consente al server di trovare il workspace corretto
Lavoro pianificato list_scheduled_bridges, create_scheduled_task, list_scheduled_task_runs Una macchina PandaPaw deve essere online; le espressioni cron usano sei campi
Provider e modelli list_providers, list_models, strumenti create/update/delete Elenca prima per usare ID correnti e tipi di modello validi
Regole e competenze sync_rules Sincronizza le istruzioni di progetto supportate saltando i file invariati

Per le definizioni dei campi di provider e modelli, vedi Provider AI personalizzati e chiavi API. Per i limiti di account e fatturazione, vedi Account, piani e costi API di PandaNpc.

Pratiche operative sicure

  • Inizia con strumenti di elenco, lettura o ricerca prima delle azioni di creazione, aggiornamento, eliminazione o pianificazione.
  • Leggi una nota prima di aggiornarla perché gli aggiornamenti delle note sostituiscono l'intero documento Markdown invece di applicare una patch.
  • Tratta i prompt pianificati come richieste di esecuzione di codice: conferma la macchina di destinazione, la directory di lavoro, il fuso orario e l'espressione cron a sei campi.
  • Tieni le chiavi API dei provider fuori da prompt e note. Inserisci i segreti solo tramite il flusso di configurazione del provider previsto.
  • Controlla la scheda di approvazione degli strumenti MCP prima di consentire azioni distruttive o esterne.
  • Usa save_done per i registri di lavoro invece di indovinare manualmente il workspace corretto e la cartella della data.

Risoluzione dei problemi

Il client dice che `pandanpc-mcp` non è stato trovato

Apri un nuovo terminale dopo l'installazione e controlla il percorso dell'eseguibile. Le applicazioni desktop a volte ereditano un PATH meno recente; configura il percorso assoluto o riavvia l'applicazione. Se npm è stato installato tramite un gestore di versioni, assicurati che il client MCP venga avviato con lo stesso utente e ambiente.

Il server è registrato ma non compare alcuno strumento

Riavvia il client, poi controlla claude mcp get pandanpc o codex mcp get pandanpc. Rimuovi e aggiungi di nuovo la voce se il comando è sbagliato. Controlla anche di non aver configurato il processo stdio locale come URL HTTP.

Gli strumenti dicono che non sei autenticato

Ripeti le due chiamate note_login. Usa il codice di verifica più recente, controlla la cartella spam e conferma che entrambe le chiamate usino lo stesso indirizzo email.

Le attività pianificate non trovano una macchina

Chiama prima list_scheduled_bridges. Se non restituisce alcun dispositivo disponibile, verifica stato di PandaPaw e connettività del dispositivo sulla macchina di destinazione. Una macchina spenta, in sospensione, disconnessa o con sessione terminata non può avviare un'esecuzione pianificata.

Un aggiornamento di una nota ha rimosso testo esistente

update_note accetta il corpo completo di sostituzione. Ripristina la nota dalla sua cronologia o dal cestino dove disponibile, poi leggi il contenuto attuale e invia il documento combinato.

Hai bisogno di aiuto specifico per l'account? Contatta support@pandanpc.com e includi il nome del client MCP, il sistema operativo, la versione del pacchetto e il messaggio di errore esatto senza segreti.