Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đã đóng
  • Có gì không ổn?
#1,009 4 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@Coding-Professional đang làm issue này rồi.

Từ ngày 11/10/2026.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
45/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
node.js, typescript
Lĩnh vực
cli

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
TypeScript
Star
856
Fork
82
Merge trung bình
6 giờ 44 phút
Pull request đã merge (30 ngày)
181

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của HelpCode-ai/anythingmcp

Tất cả issue của HelpCode-ai/anythingmcp

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.