# NitroStack × Amrita Hackathon Starter

A verified, event-ready base for building a TypeScript MCP server with the
official NitroStack SDK. The included calculator module is a working reference,
not the final hackathon idea.

## Live deployment

- Service documentation:
  <https://nitrostack-hackathon-starter-6a63c210-vedangs-org-ddf9f8a5.app.nitrocloud.ai>
- Streamable MCP endpoint:
  <https://nitrostack-hackathon-starter-6a63c210-vedangs-org-ddf9f8a5.app.nitrocloud.ai/mcp>
- NitroCloud app:
  <https://cloud.nitrostack.ai/apps/6a63c210b7c23ca10dce7c5e>

The service runs MCP protocol `2025-06-18`. A live smoke test initializes the
server, lists both tools, and executes `5 + 3 = 8`.

## Ready on this laptop

- Node.js 20.18.1 and npm 10.8.2
- Git and GitHub CLI
- VS Code
- NitroStudio 1.4.14
- Official NitroStack CLI 1.0.15 installed globally
- Official `typescript-starter` template
- Root and widget dependencies installed
- Local build, preflight checks, and GitHub Actions CI
- Idea, build, security, submission, and three-minute demo templates

## Start here

1. Complete [the short account checklist](docs/MANUAL_ACCOUNT_STEPS.md).
2. Fill in [the one-page idea brief](docs/IDEA.md) with your team.
3. Replace the calculator example with the smallest end-to-end version of your
   chosen idea.
4. Run:

   ```powershell
   npm run dev
   ```

5. In NitroStudio, choose **Add Server → Nitro Project**, select this folder,
   and open **Studio App Canvas**.

Before every push:

```powershell
npm run check
```

## Project map

```text
src/
├── index.ts
├── app.module.ts
├── health/
├── modules/
│   └── calculator/        # Replace with your MVP module
└── widgets/
    └── app/
docs/
├── IDEA.md
├── BUILD_PLAN.md
├── MANUAL_ACCOUNT_STEPS.md
├── PIZZA_REFERENCE_WORKFLOW.md
├── SUBMISSION_CHECKLIST.md
└── DEMO_SCRIPT.md
scripts/
└── preflight.mjs
```

## Commands

| Command | Purpose |
| --- | --- |
| `npm run dev` | Start the MCP server and widget dev server |
| `npm run build` | Build the production bundle |
| `npm run check` | Build, exercise the MCP server, and run preflight checks |
| `npm run smoke:mcp` | List and call MCP primitives through STDIO |
| `npm run audit:all` | Audit server and widget dependency trees |
| `npm run start:prod` | Run the built production server |
| `npm run upgrade` | Upgrade NitroStack packages |

## Non-negotiable event rules

- Use the official NitroStack TypeScript SDK throughout the project.
- Align the idea with an organizer-approved track.
- Keep `main` working and deployable.
- Deploy early to NitroCloud and test the live service after major changes.
- Never commit `.env`, API keys, tokens, passwords, credentials, private keys,
  `node_modules`, or large binaries.
- Keep the repository public through judging.
- Submit the live NitroCloud deployment, complete GitHub repository, and a demo
  video no longer than three minutes through the organizer-provided account.

See [SUBMISSION_CHECKLIST.md](docs/SUBMISSION_CHECKLIST.md) for the full gate.

## Official links

- [NitroStack documentation](https://docs.nitrostack.ai)
- [NitroStack quick start](https://docs.nitrostack.ai/quick-start)
- [NitroStudio](https://nitrostack.ai/studio)
- [NitroCloud dashboard](https://cloud.nitrostack.ai)
- [NitroStack Discord](https://discord.gg/uVWey6UhuD)
- [Coimbatore hackathon page](https://nitrostack.ai/university/6a54bc7ccc0a343237365fb3)