Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

🎃 Build an `amcp` CLI (MVP): log in with an API key, list and call tools

Chiusa
  • Qualcosa non va?
#1,009 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@Coding-Professional ci sta già lavorando.

Dal 11/10/2026.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
node.js, typescript
Ambito
cli

Direzione di ricerca

Start with the new packages/cli workspace, the root package.json workspaces and the Docker COPY lines at Dockerfile:26-32, then read mcp-combined-auth.guard.ts:61-85 for how X-API-Key is accepted and mcp-client.engine.ts:46 for the existing StreamableHTTP transport. Done means amcp login, tools ls, tools describe and tools call work against /mcp/<serverId>, the node --test suite passes with the key kept out of output, and docker build . still succeeds.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement hacktoberfest help wanted

Part of the October Challenge #997.

Why

Developers want to test a connector's tools from the terminal or a CI job ("does sap_query still answer after the upgrade?") without opening the UI or wiring up an MCP client. A small CLI that talks to the MCP endpoint we already expose is enough, and it works the same against AnythingMCP Cloud and any self-hosted instance. Comparable tools: mcp-cli, the MCP Inspector CLI mode, Composio's CLI.

Self-hosted vs Cloud

  • Self-hosted: works with per-user MCP API keys (mcp_…) and with the instance-wide MCP_API_KEY / MCP_BEARER_TOKEN used in legacy auth mode.
  • Cloud (DEPLOYMENT_MODE=cloud): works with per-user MCP API keys. Important difference: on Cloud the bare /mcp URL serves a fixed set of 8 meta-tools (anythingmcp_search_tools, anythingmcp_run_read_tool, …, see shared-toolset.ts:26 and :52), not the workspace's tools. The CLI must therefore always target a server URL /mcp/<serverId>, which exposes that server's tools directly on both deployments.
  • Who can use it: any member who can create an MCP API key. The backend already scopes everything: the key resolves to a user and organization, the per-server endpoint checks org membership (mcp-endpoint.controller.ts:837–871) and the user's MCP role limits which tools are listed and callable. The CLI adds no permissions of its own.

What to build

New workspace package packages/cli (@anythingmcp/cli, "bin": { "amcp": "dist/index.js" }, TypeScript, Node ≥ 22.12 like the root engines).

  1. Transport: @modelcontextprotocol/client v2 (already used by the backend) with StreamableHTTPClientTransport, header X-API-Key: <key>. One small dependency for argument parsing (commander or Node's built-in util.parseArgs); nothing else.
  2. Commands:
    • amcp login --url https://cloud.anythingmcp.com --server <serverId> — reads the key from a hidden prompt or --key-stdin (never as a plain argument, it would land in shell history), calls tools/list once to verify, saves a profile to ~/.config/amcp/config.json ($XDG_CONFIG_HOME respected, file mode 0600). --profile <name> for several instances.
    • amcp logout, amcp whoami (URL, server id, key prefix mcp_ab12… only).
    • amcp tools ls [--filter <text>] — name, read-only/destructive hint (from tool annotations), first line of description.
    • amcp tools describe <name> — description + input JSON schema.
    • amcp tools call <name> --args '<json>' (or --args @file.json, or - for stdin). Prints text content; if a tool annotation says destructiveHint: true and stdin is a TTY, ask for confirmation unless --yes.
    • Global --json (machine-readable output for every command), --profile, --url/--server/AMCP_URL/AMCP_API_KEY/AMCP_SERVER env overrides for CI.
  3. Exit codes: 0 ok, 1 tool returned isError, 2 usage/invalid JSON, 3 auth (401/403), 4 network/server error. Errors to stderr; never print the key or full request headers, even with --verbose.
  4. Workspace wiring: add packages/cli to root package.json workspaces; give it build, lint and test scripts. The Docker build runs npm ci with only the backend/frontend package.json copied (Dockerfile:26–32); verify docker build . still works and adjust the COPY lines if needed. The CLI must not end up in the server image.

Where to look

  • package.json (root) — workspaces, engines, test/lint scripts.
  • docs/api-reference.md:3 — the REST API under /api/* requires a JWT, not an MCP API key; :286 MCP API keys.
  • packages/backend/src/auth/mcp-combined-auth.guard.ts:61–85 — how X-API-Key (mcp_… or static key) is accepted.
  • packages/backend/src/mcp-server/mcp-endpoint.controller.ts:222 (bare /mcp), :676 (/mcp/:serverId).
  • packages/backend/src/mcp-server/shared-toolset.ts:52 — sharedEndpointMode(), why bare /mcp differs on Cloud.
  • packages/backend/src/connectors/engines/mcp-client.engine.ts:46 — existing StreamableHTTPClientTransport usage with custom headers.
  • packages/frontend/src/app/mcp-server/[id]/page.tsx:270, :297 — where users find the server URL and the X-API-Key header; add a "CLI" snippet there in a follow-up.
  • packages/backend/prisma/schema.prisma:344 — McpApiKey (optionally bound to one mcpServerId).

Acceptance criteria

  • Tests with node --test (or jest like the backend) against an in-process fake MCP server (@modelcontextprotocol/server): tools ls, tools call success, isError, 401, invalid --args JSON, --json output shape.
  • Config file is created 0600; the key never appears in stdout/stderr (test it).
  • Manually verified against a local docker compose up instance and against Cloud (put the commands/output, key redacted, in the PR).
  • The backend and frontend tests and lint still pass; docker build . still passes.
  • Docs: packages/cli/README.md + a "CLI" section in docs/api-reference.md.

Out of scope

  • amcp servers ls / connector management: there is no endpoint that lists MCP servers for an API key (/api/mcp-servers is JWT-only, mcp-servers.controller.ts:92). Follow-up: a maintainer-designed read-only endpoint, then the command.
  • OAuth device-flow / browser login, email+password login.
  • Publishing to npm, Homebrew, standalone binaries.
  • Resources and prompts (resources/list, prompts/get), interactive REPL, shell completions.

Size

L (several days, may be split: package skeleton + login/tools ls first, tools call + --json second).

How to claim

Comment "I'd like to work on this" and we'll assign you. Rules in #997.

Lingua principale
TypeScript
Stelle
856
Fork
82
Merge medio
7h 46m
PR unite (30g)
221

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di HelpCode-ai/anythingmcp

Tutte le issue di HelpCode-ai/anythingmcp

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.