@tac0de/project-bootstrap-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 wonyoung choi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# Project Bootstrap MCP — PRD
+
+This project turns the MCP (Management Control Plane) bootstrap documentation into runnable tooling: an Express-based API plus CLI that teams can publish via GitHub and npm.
+
+## 1. Project Goal
+
+- **What is this project?**  
+  An API server and CLI that surface PRD/TRD definitions, agent rules, and related operations so MCP bootstraps can be executed programmatically.
+- **What problem does it solve?**  
+  Markdown-only documentation cannot be executed; this project exposes those definitions through a lightweight service and CLI, making MCP setup automatable.
+- **Who is the primary user?**  
+  Platform engineers or operation teams bootstrapping MCPs, and any development team that installs this package via npm.
+
+## 2. Success Definition
+
+- **How do we know this project is successful?**  
+  By installing the npm package and starting the CLI/server, users can POST/GET bootstrap definitions through the provided REST endpoints.
+- **What measurable outcome must be achieved?**  
+  `npm test` passes, the Express API listens on port 4000 (default), and at least one bootstrap definition can be created and retrieved.
+- **What does failure look like?**  
+  The repository still only contains Markdown documentation or lacks automated verification for the API/CLI behavior.
+
+## 3. Core User Action
+
+- **What is the single most important action a user performs?**  
+  Run `project-bootstrap-mcp` (or `npm start`) to launch the server and interact with `/api/bootstraps`.
+- **What moment should make the user say “this works”?**  
+  A successful `POST /api/bootstraps` followed immediately by a `GET /api/bootstraps/:id` that returns the stored definition.
+
+## 4. Non-Goals
+
+- **What will this project NOT attempt to do?**  
+  It does not introduce persistent storage, authentication/authorization, multi-tenancy, or automated agent scheduling.
+- **What features are explicitly out of scope?**  
+  Connecting agents to external workflows or configuring high-availability deployments is not part of the MVP.
+
+## 5. Constraints
+
+- **Time constraints:** Deliver the MVP API, CLI, and documentation within 1–2 days.
+- **Scope constraints:** Single Node/Express service, simple CLI, and PRD/TRD CRUD operations only.
+- **Resource constraints:** No external databases; use in-memory storage and only trusted, minimal dependencies (Express and built-in Node modules).
+
+## Validation Check
+
+- **Can the project goal be explained in one sentence?** Yes — “Expose MCP bootstrap docs as runnable API/CLI tooling ready for npm/GitHub distribution.”
+- **Can success be evaluated without subjective judgment?** Yes — API functionality and `npm test` results provide objective verification.
+
+## Implementation & Usage
+
+### API Overview
+
+- `GET /api/status`: Returns service metadata (name, version), uptime, and timestamp.
+- `GET /api/bootstraps`: Lists all stored bootstrap plans.
+- `POST /api/bootstraps`: Validates and stores a bootstrap definition with `name`, `description`, `primaryAction`, and `steps`.
+- `GET /api/bootstraps/:id`: Retrieves a bootstrap plan by ID.
+
+### CLI / Execution
+
+- `npm start` or the `project-bootstrap-mcp` binary starts the server on port 4000 by default.
+- Override the port with `--port` or `-p` (e.g., `project-bootstrap-mcp --port 5000`), or set the `PORT` environment variable.
+
+### Testing & Validation
+
+- Run `npm test` to execute `node --test test/store.test.js`, which verifies the in-memory store and payload validation helper.

package/TRD.md

@@ -0,0 +1,38 @@
+# TRD — Project Bootstrap MCP
+
+This document captures the technical boundaries that support the PRD; it intentionally lives alongside PRD documentation so the architecture, data, and operational expectations are transparent for the MCP project.
+
+## 1. Architecture Direction
+
+- **Is this a single-user tool or multi-user system?**  
+  A single-process tool targeting the platform or operations team that owns the MCP bootstrap; multi-tenant or concurrent-user support is explicitly deferred to later phases.
+- **Is persistence required?**  
+  Not for the MVP. In-memory storage suffices, but the `BootstrapStore` abstraction allows replacing the backing store with a file or database in the future.
+- **Is real-time behavior required?**  
+  No. RESTful request/response cycles (ms latency) are adequate; streaming or WebSocket behavior is out of scope for now.
+
+## 2. Data Model Boundaries
+
+- **What data MUST be stored?**  
+  Bootstrap plan metadata such as name, description, primary action, step list, and timestamps must be retained in memory for GET endpoints.
+- **What data MUST NOT be stored?**  
+  Authentication credentials, secret keys, or any sensitive tokens must never enter the store.
+- **What data can be derived instead of persisted?**  
+  Runtime metrics (e.g., total bootstrap count) are computed on demand rather than persistently stored.
+
+## 3. Technology Constraints
+
+- **Required technologies:** Node.js 18+, Express, and the built-in `node:test` module for validation.
+- **Forbidden technologies:** External databases, ORMs, authentication frameworks, and TypeScript (current focus is CommonJS).
+- **Justification for constraints:** Keeping the stack minimal accelerates npm publishing and keeps the package lightweight for quick bootstraps.
+
+## 4. Operational Constraints
+
+- **Expected scale:** Tens of concurrent requests at most; a single process serving on port 4000 (customizable via CLI flags).
+- **Performance expectations:** Responses should stay in the millisecond range without caching or database overhead.
+- **Security or compliance requirements:** Does not collect sensitive data, but CORS or authentication middleware can be layered on later if needed.
+
+## Validation Check
+
+- **Do technical choices support the PRD goals?** Yes, the Express/CLI stack fulfills the API delivery and documentation-driven outcome defined in the PRD.
+- **Are any technical decisions premature or unnecessary?** No, everything beyond in-memory storage or REST endpoints is deferred until future phases.

package/bin/project-bootstrap-mcp.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+const startServer = require('../src/server');
+
+function parsePort(args, envPort) {
+  let portValue = envPort || '4000';
+  args.forEach((arg, index, list) => {
+    if (arg === '--port' && list[index + 1]) {
+      portValue = list[index + 1];
+    }
+    if (arg.startsWith('--port=')) {
+      portValue = arg.split('=')[1];
+    }
+    if (arg === '-p' && list[index + 1]) {
+      portValue = list[index + 1];
+    }
+  });
+  const parsed = Number.parseInt(portValue, 10);
+  if (Number.isNaN(parsed)) {
+    console.error(`invalid port value: ${portValue}`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+const port = parsePort(process.argv.slice(2), process.env.PORT);
+startServer({ port });

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tac0de/project-bootstrap-mcp",
+  "version": "1.0.0",
+  "description": "Project Bootstrap MCP API tooling for launching MCP bootstrap definitions and documentation.",
+  "main": "src/index.js",
+  "bin": {
+    "project-bootstrap-mcp": "bin/project-bootstrap-mcp.js"
+  },
+  "scripts": {
+    "start": "node ./bin/project-bootstrap-mcp.js",
+    "test": "node --test test/store.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "bootstrap",
+    "api",
+    "cli",
+    "project-tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "wonyoung choi",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "test",
+    "LICENSE",
+    "README.md",
+    "TRD.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/project-bootstrap-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/project-bootstrap-mcp/issues"
+  },
+  "homepage": "https://github.com/your-org/project-bootstrap-mcp#readme",
+  "dependencies": {
+    "express": "^4.19.2"
+  }
+}

package/src/app.js

@@ -0,0 +1,71 @@
+const express = require('express');
+const path = require('path');
+const { validateBootstrapPayload } = require('./validators');
+const BootstrapStore = require('./store');
+
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+
+function createApp(options = {}) {
+  const store = options.store || new BootstrapStore();
+  const app = express();
+
+  app.use(express.json());
+
+  app.get('/api/status', (req, res) => {
+    res.json({
+      service: pkg.name,
+      version: pkg.version,
+      uptime: process.uptime(),
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  app.get('/api/bootstraps', (req, res) => {
+    res.json({ items: store.list() });
+  });
+
+  app.post('/api/bootstraps', (req, res) => {
+    const validation = validateBootstrapPayload(req.body);
+    if (!validation.valid) {
+      return res.status(400).json({ errors: validation.errors });
+    }
+    const payload = {
+      name: req.body.name,
+      description: req.body.description,
+      primaryAction: req.body.primaryAction,
+      targetPlatforms: Array.isArray(req.body.targetPlatforms)
+        ? req.body.targetPlatforms
+        : [],
+      successCriteria: Array.isArray(req.body.successCriteria)
+        ? req.body.successCriteria
+        : [],
+      steps: req.body.steps,
+    };
+    const saved = store.add(payload);
+    res.status(201).json(saved);
+  });
+
+  app.get('/api/bootstraps/:id', (req, res) => {
+    const record = store.find(req.params.id);
+    if (!record) {
+      return res.status(404).json({ error: 'bootstrap not found' });
+    }
+    res.json(record);
+  });
+
+  app.use((req, res) => {
+    res.status(404).json({ error: 'not found' });
+  });
+
+  app.use((err, req, res, next) => {
+    /* eslint-disable no-console */
+    console.error('internal error', err);
+    /* eslint-enable no-console */
+    res.status(500).json({ error: 'internal server error' });
+    next(err);
+  });
+
+  return { app, store };
+}
+
+module.exports = createApp;

package/src/index.js

@@ -0,0 +1,9 @@
+const BootstrapStore = require('./store');
+const createApp = require('./app');
+const startServer = require('./server');
+
+module.exports = {
+  BootstrapStore,
+  createApp,
+  startServer,
+};

package/src/server.js

@@ -0,0 +1,29 @@
+const createApp = require('./app');
+
+function startServer({ port = process.env.PORT || 4000, onStart } = {}) {
+  const { app } = createApp();
+  const server = app.listen(port, () => {
+    const message = `Project Bootstrap MCP listening on port ${port}`;
+    if (typeof onStart === 'function') {
+      onStart(message, port);
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(message);
+    }
+  });
+
+  const graceful = () => {
+    server.close(() => {
+      // eslint-disable-next-line no-console
+      console.log('Project Bootstrap MCP shutting down');
+      process.exit(0);
+    });
+  };
+
+  process.on('SIGINT', graceful);
+  process.on('SIGTERM', graceful);
+
+  return { app, server };
+}
+
+module.exports = startServer;

package/src/store.js

@@ -0,0 +1,27 @@
+class BootstrapStore {
+  constructor() {
+    this.items = new Map();
+    this.counter = 1;
+  }
+
+  list() {
+    return Array.from(this.items.values());
+  }
+
+  add(payload) {
+    const id = String(this.counter++);
+    const record = {
+      id,
+      createdAt: new Date().toISOString(),
+      ...payload,
+    };
+    this.items.set(id, record);
+    return record;
+  }
+
+  find(id) {
+    return this.items.get(id) ?? null;
+  }
+}
+
+module.exports = BootstrapStore;

package/src/validators.js

@@ -0,0 +1,34 @@
+function validateBootstrapPayload(payload) {
+  const errors = [];
+  if (!payload || typeof payload !== 'object') {
+    errors.push('payload must be an object');
+    return { valid: false, errors };
+  }
+
+  const { name, description, primaryAction, steps } = payload;
+  if (!name || typeof name !== 'string') {
+    errors.push('name is required and must be a string');
+  }
+  if (!description || typeof description !== 'string') {
+    errors.push('description is required and must be a string');
+  }
+  if (!primaryAction || typeof primaryAction !== 'string') {
+    errors.push('primaryAction is required and must be a string');
+  }
+  if (!Array.isArray(steps) || steps.length === 0) {
+    errors.push('steps must be a non-empty array');
+  } else {
+    steps.forEach((step, index) => {
+      if (!step || typeof step.title !== 'string') {
+        errors.push(`steps[${index}].title is required`);
+      }
+      if (!step || typeof step.detail !== 'string') {
+        errors.push(`steps[${index}].detail is required`);
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = { validateBootstrapPayload };

package/test/store.test.js

@@ -0,0 +1,44 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const BootstrapStore = require('../src/store');
+const { validateBootstrapPayload } = require('../src/validators');
+
+test('BootstrapStore should add and list records', () => {
+  const store = new BootstrapStore();
+  const payload = {
+    name: 'bootstrap-a',
+    description: 'test',
+    primaryAction: 'deploy',
+    steps: [
+      { title: 'step1', detail: 'run' },
+    ],
+  };
+
+  const record = store.add(payload);
+  assert.strictEqual(record.name, payload.name);
+  assert.strictEqual(record.id, '1');
+  const items = store.list();
+  assert.strictEqual(items.length, 1);
+  assert.strictEqual(store.find('1'), record);
+});
+
+test('BootstrapStore returns null for missing id', () => {
+  const store = new BootstrapStore();
+  assert.strictEqual(store.find('missing'), null);
+});
+
+test('validateBootstrapPayload rejects invalid data', () => {
+  const result = validateBootstrapPayload({});
+  assert.strictEqual(result.valid, false);
+  assert.ok(result.errors.length >= 1);
+});
+
+test('validateBootstrapPayload accepts valid payload', () => {
+  const result = validateBootstrapPayload({
+    name: 'valid',
+    description: 'desc',
+    primaryAction: 'run',
+    steps: [{ title: 't', detail: 'd' }],
+  });
+  assert.strictEqual(result.valid, true);
+});