Kira4i MCP Server for Next.js

An MCP (Model Context Protocol) server specifically designed for Next.js projects, exposing a curated dependency catalog organized by categories, a category-selection prompt for LLMs, and tools to read the current project's dependencies and apply/merge recommended dependencies into package.json (creating it if missing).

Built with TypeScript and @modelcontextprotocol/sdk.

Features

• list_categories — returns the full catalog with per-category descriptions.
• selection_prompt — returns a ready-to-use prompt to let the LLM pick categories from the catalog based on a task.
• list_conventions — surfaces convention sets that encode Kira4i project guardrails.
• conventions_selection_prompt — provides a ready-to-use prompt to choose the right convention sets for a task.
• conventions_prompt — formats the requested convention sets into markdown ready for AGENTS.md or general workflow prompts.
• resolve_conventions — returns the structured guideline data for chosen convention keys.
• resolve_dependencies — merges dependencies/devDependencies for selected categories and returns a single plan.
• read_current_dependencies — reads dependencies/devDependencies from package.json (if present).
• apply_dependencies_to_package_json — creates/updates package.json by merging the resolved plan.
• run_lint_checks — runs lint-staged commands on changed files and returns error summary.

Categories are split into individual YAML files under data/categories/* for readability and maintainability. Conventions live alongside them in data/conventions/* and can be stitched into prompts programmatically.

Convention Sets

Each YAML file in data/conventions captures a thematic set of guardrails (e.g., Next.js architecture, Supabase usage, game rendering choices). They include:

• A unique key, title, and description.
• scope entries describing when to apply the set.
• Optional tags for quick filtering.
• A guidelines array with levelled directives (must, should, consider) and rationale.

Use list_conventions or import buildConventionsPrompt to weave these guardrails into AGENTS.md, onboarding guides, or per-feature workflows.

Note: All dependency categories are specifically curated for Next.js projects, providing essential and supplementary libraries to enhance Next.js applications with features like UI styling, state management, authentication, data validation, and specialized capabilities such as game development or data visualization.

Install & Run

pnpm i   # or npm i / yarn
pnpm build
pnpm start   # runs the built server over stdio
# OR run in dev (TypeScript via tsx)
pnpm dev

If you are wiring this MCP server into a client, point it to node ./dist/server.js (or tsx src/server.ts during development).

Command Line Options

You can control which tools are available by passing command line arguments when starting the server:

• --disable-read-deps — Disables the read_current_dependencies tool
• --disable-apply-deps — Disables the apply_dependencies_to_package_json tool

Examples

# Disable only the read dependencies tool
node ./dist/server.js --disable-read-deps

# Disable only the apply dependencies tool
node ./dist/server.js --disable-apply-deps

# Disable both tools
node ./dist/server.js --disable-read-deps --disable-apply-deps

# Default behavior (both tools enabled)
node ./dist/server.js

Note: By default, both tools are enabled. These flags allow you to selectively disable tools based on your security requirements or operational needs.

Tooling Contracts

This server exposes the following MCP tools:

• list_categories → { categories: Array<{ key, description, dependencies, devDependencies }> }
• selection_prompt → { text: string } (also returned as a text content item)
• list_conventions → { conventions: Array<{ key, title, description, scope, guidelines }> }
• conventions_selection_prompt → { text: string } (returns the ready-to-use selection prompt)
• conventions_prompt (input: { keys?: string[], intro?: string, includeCatalog?: boolean, headingLevel?: number }) → { text }
• resolve_conventions (input: { keys: string[] }) → { conventions: ConventionSet[] }
• resolve_dependencies (input: { categories: string[] }) → { dependencies, devDependencies, notes }
• read_current_dependencies (input: { projectPath?: string }) → { dependencies, devDependencies }
• apply_dependencies_to_package_json (input: { categories?: string[], plan?: {dependencies,devDependencies}, projectPath?: string, createIfMissing?: boolean }) → { created, updated, before, after, added, changed }
• run_lint_checks (input: { projectPath?: string }) → { errors: Array<{ command: string, errors: Array<{ file: string | null, message: string }> }> }

Either pass categories to compute a plan server-side, or pass a plan you computed with resolve_dependencies. If package.json is missing and createIfMissing is true (default), a minimal one is created.

LLM Flow (suggested)

1. Call list_categories to retrieve the catalog.
2. Use the text from selection_prompt to decide which categories fit the user's task.
3. Call resolve_dependencies with the selected category keys to get a merged dependency plan.
4. (Optional) Call read_current_dependencies to see what is already present in the repository.
5. Call apply_dependencies_to_package_json with either categories or the plan from step 3.

Convention Workflow

1. Call list_conventions to inspect the available guardrail sets.
2. Hand the conventions_selection_prompt text to your LLM so it can pick the relevant convention keys for the task.
3. Use resolve_conventions to fetch the structured guideline payload for the chosen keys (great for dashboards or auditing).
4. Feed the same keys into conventions_prompt to get richly formatted guidance for AGENTS.md or other docs.

Notes

• This server does not install packages; it only maintains package.json. After applying, run your package manager.
• Version conflicts are resolved by taking the highest semver where possible.
• The catalog content in data/categories/* is derived from your provided specification.

One-call apply via MCP

You can skip a second call by setting apply: true on resolve_dependencies:

{
  "name": "resolve_dependencies",
  "arguments": {
    "categories": ["core-web-framework", "ui-styling-components"],
    "apply": true,
    "projectPath": ".",
    "createIfMissing": true
  }
}

Response contains { plan, applied: true, outcome }.

Programmatic (package) usage

import {
  listCategories,
  resolveDependenciesForCategoryKeys,
  resolveAndApply,
  buildCategorySelectionPrompt,
  buildConventionSelectionPrompt,
  buildConventionsPrompt,
  resolveConventionKeys
} from "@kira4i/mcp-kira";

// 1) let your agent decide categories using the prompt text
const prompt = buildCategorySelectionPrompt("Use default conventions; add gamedev if building a game");

// Let an agent auto-select convention sets for the task at hand
const conventionSelector = buildConventionSelectionPrompt("Prioritise Supabase usage and game readiness when mentioned.");

// Resolve structured guideline data (same shape the resolve_conventions tool returns)
const { sets: conventionDetails } = resolveConventionKeys([
  "next-app-architecture",
  "project-module-boundaries"
]);

// Build a conventions prompt for AGENTS.md scaffolding
const conventions = buildConventionsPrompt([
  "next-app-architecture",
  "project-module-boundaries",
  "ui-ux-foundations"
]);

// 2) resolve only
const plan = resolveDependenciesForCategoryKeys(["core-web-framework", "ui-styling-components"]);

// 3) resolve and apply in one go
const { plan: finalPlan, outcome } = await resolveAndApply({
  categories: ["core-web-framework", "ui-styling-components"],
  projectPath: ".",
  createIfMissing: true
});

console.log(outcome.added, outcome.changed);

Publishing

This package is published to npm as @kira4i/mcp-kira. Manual publishing process required.

Local Development

# Install dependencies
pnpm install

# Build for development
pnpm build

# Run the server in development mode
pnpm dev

# Validate data files
pnpm validate-data

Test commit to verify pre-commit hook fix

Test commit to verify pre-commit hook fix