Skip to content

USAGE.md

Latest commit

 

History

History
42 lines (36 loc) · 3.03 KB

USAGE.md

File metadata and controls

42 lines (36 loc) · 3.03 KB

Repository Usage Guide

Getting Started

  1. Install dependencies: npm install.
  2. Copy .env.example to .env and set MCP_BASIC_KEY, MCP_PAPERSCORE_KEY, and any other secrets required by the agents.
  3. Run npm run start to boot the API via ts-node, or use make dev for the auto-rebuilding Docker dev stack (api-dev service). make build && make up builds and starts the production docker-compose stack locally.

Local Testing and Builds

  • npm test: runs the Jest suites in src/*.test.ts and any request tests.
  • npm run test:coverage: produces a coverage report under coverage/.
  • npm run build: compiles TypeScript into dist/ and copies src/templates/.
  • npm run serve: executes the compiled dist/app.js using Node. Use these commands locally before pushing to keep CI green.

Publishing to GitHub Container Registry (GHCR)

The repository publishes multi-architecture images to ghcr.io/<owner>/paperdebugger-mcp-server via the Build and Push Docker Image workflow (.github/workflows/build.yaml). When you push to main or open/update a pull request targeting main, GitHub Actions:

  1. Checks out the repo (with submodules) using actions/checkout.
  2. Sets up Buildx and authenticates to GHCR with ${{ secrets.GITHUB_TOKEN }}.
  3. Generates tags for the branch, PR, and short SHA through docker/metadata-action.
  4. Builds docker/Dockerfile for linux/amd64 and linux/arm64 and pushes all tags to GHCR. Manual publishing is rarely needed, but you can mimic the pipeline locally: docker build -t ghcr.io/<owner>/paperdebugger-mcp-server:dev -f docker/Dockerfile . and then docker push ghcr.io/<owner>/paperdebugger-mcp-server:dev after docker login ghcr.io with a PAT scoped to packages.

Pulling the Latest Image from GitHub

To consume the newest container, pull the tag emitted by the workflow:

docker pull ghcr.io/<owner>/paperdebugger-mcp-server:main
docker pull ghcr.io/<owner>/paperdebugger-mcp-server:main-<short_sha>

Tags main, pr-<id>, and <branch>-<short_sha> are updated during each run; production deployments typically use the main tag or a specific SHA tag for reproducibility.

GitHub Actions Overview

Build and Push Docker Image

  • Trigger: push to main or PR targeting main.
  • Inputs: repository source, ${{ secrets.PERSONAL_ACCESS_TOKEN }} for checkout, ${{ secrets.GITHUB_TOKEN }} for GHCR login.
  • Process: checkout → Buildx setup → tag calculation → multi-arch build → push to GHCR (with caching via type=gha).
  • Output: versioned Docker images stored in GHCR plus workflow metadata (tags, labels).

Test Coverage Workflow

  • Trigger: push or PR against main or develop.
  • Inputs: codebase, Node 20 runtime, secrets like MCP_AUTO_TEST_KEY for OpenAI calls.
  • Process: checkout → npm ci → npm run test:coverage → upload coverage/ artifact → append summary → comment on PR (when applicable).
  • Output: stored coverage artifact, GitHub step summary, and a PR comment showing line/function/branch/statement coverage.