@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/mcp-server/CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing to {{projectName}}
+
+Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Commit Guidelines](#commit-guidelines)
+- [Pull Request Process](#pull-request-process)
+- [Code Style](#code-style)
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We welcome contributors from all backgrounds and experience levels.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/{{projectName}}.git`
+3. Add upstream remote: `git remote add upstream https://github.com/ORIGINAL_OWNER/{{projectName}}.git`
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js >= 20.0.0
+- pnpm (recommended) or npm
+
+### Installation
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build
+
+# Run in development mode (with watch)
+pnpm dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage
+pnpm test:coverage
+```
+
+### Code Quality
+
+```bash
+# Type checking
+pnpm typecheck
+
+# Linting
+pnpm lint
+pnpm lint:fix
+
+# Formatting
+pnpm format
+```
+
+## Making Changes
+
+1. Create a new branch from `main`:
+
+   ```bash
+   git checkout -b feat/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+2. Make your changes following the code style guidelines
+
+3. Test your changes locally
+
+4. Commit your changes following the commit guidelines
+
+## Commit Guidelines
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.
+
+### Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type       | Description                                        |
+| ---------- | -------------------------------------------------- |
+| `feat`     | New feature                                        |
+| `fix`      | Bug fix                                            |
+| `docs`     | Documentation only                                 |
+| `style`    | Code style (formatting, missing semi-colons, etc.) |
+| `refactor` | Code refactoring (no functional changes)           |
+| `perf`     | Performance improvement                            |
+| `test`     | Adding or updating tests                           |
+| `chore`    | Maintenance tasks                                  |
+
+### Examples
+
+```bash
+feat(tools): add new tool for data processing
+fix(resources): handle empty response correctly
+docs: update installation instructions
+refactor(core): simplify request handling logic
+```
+
+## Pull Request Process
+
+1. Update documentation if needed
+2. Ensure all tests pass: `pnpm test`
+3. Ensure code quality checks pass: `pnpm lint && pnpm typecheck`
+4. Fill out the pull request template completely
+5. Request review from maintainers
+
+### PR Title
+
+Use the same format as commit messages:
+
+```
+feat(tools): add new tool for data processing
+```
+
+## Code Style
+
+### TypeScript
+
+- Use TypeScript strict mode
+- Prefer `interface` over `type` for object shapes
+- Use explicit return types for public functions
+- Avoid `any` - use `unknown` if type is truly unknown
+
+### Formatting
+
+- We use Prettier for code formatting
+- Run `pnpm format` before committing
+- EditorConfig is provided for consistent editor settings
+
+### File Organization
+
+```
+src/
+├── index.ts        # Entry point
+├── tools.ts        # MCP tools
+├── resources.ts    # MCP resources
+├── services/       # Business logic services
+├── types/          # TypeScript type definitions
+└── utils/          # Utility functions
+```
+
+### Naming Conventions
+
+| Type       | Convention       | Example             |
+| ---------- | ---------------- | ------------------- |
+| Files      | kebab-case       | `data-processor.ts` |
+| Classes    | PascalCase       | `DataProcessor`     |
+| Functions  | camelCase        | `processData()`     |
+| Constants  | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`   |
+| Interfaces | PascalCase       | `ProcessorConfig`   |
+
+## Questions?
+
+If you have questions, feel free to:
+
+- Open an issue with the "question" label
+- Check existing issues and discussions
+
+Thank you for contributing!

package/dist/resources/templates/mcp-server/Dockerfile

@@ -0,0 +1,23 @@
+FROM node:lts-alpine
+
+# Install pnpm globally
+RUN npm install -g pnpm
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files and install dependencies (cache layer)
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# Copy all source files
+COPY . .
+
+# Build the project
+RUN pnpm run build
+
+# Install this package globally so that the command is available
+RUN npm install -g .
+
+# Default command to run the MCP server
+CMD [ "node", "dist/index.js", "--stdio" ]

package/dist/resources/templates/mcp-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} {{author}}
+
+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/dist/resources/templates/mcp-server/README.md

@@ -0,0 +1,123 @@
+# {{projectName}}
+
+MCP (Model Context Protocol) server.
+
+## Features
+
+- 🔧 Built with TypeScript and MCP SDK
+- 🧪 Vitest for testing
+- 📦 tsup for bundling
+- 🔍 ESLint + Prettier for code quality
+- 🪝 Husky + lint-staged for git hooks
+- 📝 Conventional commits with commitlint
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development (with watch mode)
+pnpm dev
+
+# Build
+pnpm build
+
+# Run in stdio mode
+pnpm start:stdio
+```
+
+## MCP Configuration
+
+### For Cursor / Claude Desktop / Windsurf
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "{{projectName}}": {
+      "command": "node",
+      "args": ["/path/to/{{projectName}}/dist/index.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Using npx (after publishing)
+
+```json
+{
+  "mcpServers": {
+    "{{projectName}}": {
+      "command": "npx",
+      "args": ["-y", "{{projectName}}"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool       | Description            |
+| ---------- | ---------------------- |
+| `hello`    | Say hello to someone   |
+| `get_info` | Get server information |
+
+## Available Resources
+
+| Resource                 | Description |
+| ------------------------ | ----------- |
+| `{{projectName}}://help` | Usage guide |
+
+## Development
+
+```bash
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+pnpm lint:fix
+
+# Format
+pnpm format
+
+# Test
+pnpm test
+pnpm test:watch
+pnpm test:coverage
+
+# Inspect with MCP Inspector
+pnpm inspect
+```
+
+## Publishing
+
+```bash
+# Build and publish to npm
+pnpm pub:release
+
+# Or create a local package
+pnpm publish:local
+```
+
+## Docker
+
+```bash
+# Build image
+docker build -t {{projectName}} .
+
+# Run container
+docker run -it {{projectName}}
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+MIT © {{author}}

package/dist/resources/templates/mcp-server/_gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+
+# Test coverage
+coverage/
+
+# Cache
+.cache/

package/dist/resources/templates/mcp-server/commitlint.config.js

@@ -0,0 +1,24 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "type-enum": [
+      2,
+      "always",
+      [
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "perf",
+        "test",
+        "build",
+        "ci",
+        "chore",
+        "revert",
+      ],
+    ],
+    "subject-case": [0],
+    "header-max-length": [2, "always", 100],
+  },
+};

package/dist/resources/templates/mcp-server/eslint.config.js

@@ -0,0 +1,30 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+import prettierConfig from "eslint-config-prettier";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  prettierConfig,
+  {
+    ignores: ["dist/**", "node_modules/**", "*.config.js"],
+  },
+  {
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+    },
+    rules: {
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        { prefer: "type-imports", fixStyle: "inline-type-imports" },
+      ],
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+      "prefer-const": "error",
+      "no-var": "error",
+    },
+  },
+);

package/dist/resources/templates/mcp-server/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.1",
+  "description": "MCP server for {{projectName}}",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "{{projectName}}": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "start:stdio": "node dist/index.js --stdio",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "inspect": "pnpx @modelcontextprotocol/inspector",
+    "mcp-test": "pnpm start -- --stdio",
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm test && pnpm build",
+    "pub:release": "pnpm build && npm publish --access public",
+    "publish:local": "pnpm build && npm pack",
+    "prepare": "husky || true"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/{{author}}/{{projectName}}.git"
+  },
+  "homepage": "https://github.com/{{author}}/{{projectName}}#readme",
+  "bugs": {
+    "url": "https://github.com/{{author}}/{{projectName}}/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai"
+  ],
+  "author": "{{author}}",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/dist/resources/templates/mcp-server/src/index.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+
+const server = new McpServer({
+  name: "{{projectName}}",
+  version: "0.1.0",
+});
+
+// Register tools
+registerTools(server);
+
+// Register resources
+registerResources(server);
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("{{projectName}} MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/dist/resources/templates/mcp-server/src/resources.ts

@@ -0,0 +1,33 @@
+import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export function registerResources(server: McpServer): void {
+  // Example resource: help
+  server.resource("help", "{{projectName}}://help", async () => {
+    return {
+      contents: [
+        {
+          uri: "{{projectName}}://help",
+          mimeType: "text/markdown",
+          text: `# {{projectName}} MCP Server
+
+## Available Tools
+
+### hello
+Say hello to someone.
+- **name** (required): Name to greet
+
+### get_info
+Get server information.
+
+## Usage
+
+This is a template MCP server. Customize it by:
+1. Adding new tools in \`src/tools.ts\`
+2. Adding new resources in \`src/resources.ts\`
+3. Adding services in \`src/services/\`
+`,
+        },
+      ],
+    };
+  });
+}

package/dist/resources/templates/mcp-server/src/tools.ts

@@ -0,0 +1,43 @@
+import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export function registerTools(server: McpServer): void {
+  // Example tool: hello
+  server.tool(
+    "hello",
+    "Say hello to someone",
+    {
+      name: z.string().describe("Name to greet"),
+    },
+    async ({ name }) => {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Hello, ${name}! Welcome to {{projectName}}.`,
+          },
+        ],
+      };
+    },
+  );
+
+  // Example tool: get_info
+  server.tool("get_info", "Get server information", {}, async () => {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              name: "{{projectName}}",
+              version: "0.0.1",
+              description: "MCP server template",
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  });
+}

package/dist/resources/templates/mcp-server/src/types/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Common types for {{projectName}}
+ */
+
+export interface ServerConfig {
+  name: string;
+  version: string;
+  debug?: boolean;
+}
+
+export interface ToolResult {
+  content: Array<{
+    type: "text" | "image" | "resource";
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  }>;
+  isError?: boolean;
+}

package/dist/resources/templates/mcp-server/src/utils/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Utility functions for {{projectName}}
+ */
+
+/**
+ * Safely parse JSON with error handling
+ */
+export function safeJsonParse<T>(json: string): T | null {
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delay execution for specified milliseconds
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Format error message for MCP response
+ */
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/dist/resources/templates/mcp-server/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}