# Forge Space Core

> Shared standards, MCP context server, and architectural patterns for the Forge Space ecosystem.

- **Type:** MCP server
- **Install:** `agentstack add mcp-forge-space-core`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Forge-Space](https://agentstack.voostack.com/s/forge-space)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Forge-Space](https://github.com/Forge-Space)
- **Source:** https://github.com/Forge-Space/core
- **Website:** https://github.com/Forge-Space/core

## Install

```sh
agentstack add mcp-forge-space-core
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Forge-Space Core
  Shared standards, patterns, and MCP context server for the Forge Space ecosystem.

[](https://github.com/Forge-Space/core/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](CONTRIBUTING.md)
[](https://www.npmjs.com/package/@forgespace/core)

Part of [Forge Space](https://github.com/Forge-Space) — the open full-stack AI workspace. This repo provides the foundation that all other Forge Space projects build on: code quality standards, security framework, CI/CD workflows, and a local MCP context server for IDE integration.

## Overview

Forge-Space Core provides shared configurations, workflows, and architectural patterns for consistency across the ecosystem. Centralized feature toggles, reusable GitHub Actions workflows (95% reduction in maintenance overhead), and comprehensive security validation.

### Key Features

- 🔒 **Zero Secrets**: Public repository with comprehensive security validation
- 🏗️ **Architectural Patterns**: Proven patterns for scalable applications
- 🔄 **Automation**: Scripts and workflows for consistent project setup
- 📊 **Quality Standards**: 80% test coverage, linting, and security scanning
- 🛡️ **Security First**: Built-in security scanning and validation
- 🐳 **Docker Patterns**: Containerization and deployment patterns
- 🎛️ **Centralized Feature Toggles**: Cross-project feature management with CLI control
- 📡 **MCP Context Server**: Local stdio MCP server exposing all Forge Space project context documents as resources
- 📝 **Logger Module**: Comprehensive logging with observability and distributed tracing
- 🚀 **High Performance**: Sub-100ms integration times and optimized patterns
- 🔄 **GitHub Workflows Optimization**: Organization-level reusable workflows eliminating duplication
- 🔐 **SHA-Pinned Automation**: Workflow/action references use full commit SHAs for supply-chain safety

## Tenant Isolation Standard

Forge-Space Core now defines an explicit tenant contract and enforces decoupling checks
to keep platform code tenant-agnostic.

- Contract export: `TenantProfile` and validators from `src/tenant/contract.ts`
- Required profile keys:
  - `tenant_id`
  - `github_owner`
  - `sonar_org`
  - `npm_scope`
  - `quality_policy`
  - `ci_policy`
- CI guardrail: `npm run check:tenant-decoupling`
  - Blocks tenant-specific hardcodes in platform paths (`src`, `patterns`, `scripts`, `.github`)
  - Uses `rg` when available and automatically falls back to `grep` on constrained runners
  - Allowed references should live in dedicated tenant profile repositories or explicit examples
  - Works in CI/local environments with `rg` or `grep` fallback

## Test Autogen — Phase 0 (Warn)

Phase 0 is active in warn-only mode to guide contributors without blocking delivery:

- Local hooks (`.husky/pre-commit`, `.husky/pre-push`) run `forge-ai-init test-autogen` only
  when `FORGE_TENANT_ID` and `FORGE_TENANT_PROFILE_REF` are set, and always exit `0` in phase 0.
- Pull requests run CI job `test-autogen-warn` using `forge-ai-action` with:
  - `command: test-autogen-check`
  - `tenant: acme-sandbox`
  - `tenant_profile_ref: .forge-tenant-profiles/tenants/acme-sandbox/profile.yaml`
  - `test_autogen_phase: warn`
  - PR feedback enabled (`comment: true`, `annotations: true`)
  - Cross-repo profile checkout token: `FORGE_TENANT_PROFILES_READ_TOKEN` (fallback: `GITHUB_TOKEN`)
  - External tenant profile checkout is best-effort; if unavailable, parity is skipped
    and the warn-only flow remains non-blocking

This phase highlights missing tests early while preserving non-blocking developer flow.

## Lint Toolchain Compatibility

Keep `@typescript-eslint/eslint-plugin`, `@typescript-eslint/parser`, and
`typescript-eslint` on the same minor version to avoid `npm ci` peer-dependency
resolution failures in CI.

## 📋 Projects Using These Patterns

- **[siza](https://github.com/Forge-Space/siza)**: Next.js web application with multi-environment deployment
- **[ui-mcp](https://github.com/Forge-Space/ui-mcp)**: MCP server for AI-powered UI generation
- **[mcp-gateway](https://github.com/Forge-Space/mcp-gateway)**: Python/Node.js MCP gateway with comprehensive CI/CD
- **[branding-mcp](https://github.com/Forge-Space/branding-mcp)**: AI-powered brand identity generation
- **[siza-gen](https://github.com/Forge-Space/siza-gen)**: AI generation engine with component registry

## 🌐 Ecosystem Integration

This core repository provides the foundation for the entire Forge Space ecosystem:

- **🔗 Shared Standards**: Consistent coding patterns across all projects
- **🛡️ Security Framework**: Unified security validation and scanning
- **🔄 Automation**: Centralized workflows and CI/CD pipelines
- **📊 Quality Gates**: Standardized testing and quality requirements

**Related Projects:**
- [**Siza**](https://github.com/Forge-Space/siza) - AI-powered full-stack workspace
- [**MCP Gateway**](https://github.com/Forge-Space/mcp-gateway) - Central tool aggregation and routing
- [**ui-mcp**](https://github.com/Forge-Space/ui-mcp) - MCP server for UI generation

**Documentation:**
- [**Documentation Hub**](docs/README.md) - Complete documentation
- [**Project Context**](docs/project/PROJECT_CONTEXT.MD) - Project guide and context

## IDP — Internal Developer Platform

CLI tools for project governance, shipped as part of `@forgespace/core`:

| Tool | Command | Purpose |
|------|---------|---------|
| **Scorecard** | `npx forge-scorecard` | Evaluate project quality across security, quality, performance, compliance |
| **Policy Engine** | `npx forge-policy` | Enforce governance policies with block/warn/log actions |
| **Init** | `npx forge-init` | Bootstrap governance for any project |
| **Feature Toggles** | `npx forge-features` | Manage file-based feature toggles |
| **Audit** | `npx forge-audit` | Assess legacy codebase migration readiness |

### Runtime Import Safety

Importing `@forgespace/core` is side-effect free. Governance scaffolding runs only when
`forge-init` is executed as a CLI command (`npx forge-init` or `forge-init` binary), not when the
package is imported in application runtime code.

`forge-audit` evaluates 6 categories: dependencies, architecture, security,
quality, migration-readiness, and ai-governance.

### Quick Start

```bash
npx forge-init --template nextjs   # Next.js project with SSR + bundle policies
npx forge-init --template react    # React with accessibility + component coverage
npx forge-init --template node     # Node.js with dependency audit + API validation
npx forge-init                     # Base governance (no framework-specific rules)

npx forge-audit --dir /path/to/legacy-app       # Migration assessment
npx forge-audit --json --threshold 60            # CI gate mode
```

### Guides

- [Scorecard Integration](docs/guides/scorecard-integration.md) — add quality scorecards to any repo
- [Policy Engine Integration](docs/guides/policy-engine-integration.md) — add policy checks to any repo
- [Security Spoke Contract v1](docs/guides/security-spoke-contract.md) — shared scanner output contract

### Security Spoke Contract v1

Security scanner outputs across Forge Space use the canonical v1 contract in
`patterns/idp/security-spoke`.

- Report schema:
  `patterns/idp/security-spoke/schema/security-spoke-report-v1.schema.json`
- Rule catalog:
  `patterns/idp/security-spoke/rules/security-spoke-rules-v1.json`
- Compatibility fixtures:
  `patterns/idp/security-spoke/fixtures/*.json`

## � GitHub Workflows Optimization

### Canonical Workflow Source

Reusable workflows are now centralized in **`Forge-Space/.github`**. This
repository (`core`) provides bootstrap orchestration and templates for new
projects.

### Limit-Aware CI (New Orgs + New Projects)

New projects generated by `scripts/bootstrap/project.sh` default to the
`limit-aware` CI profile:

- baseline checks always run: lint, typecheck, unit tests, build, secret scan
- heavy jobs degrade when Actions usage crosses configured thresholds:
  - Docker build
  - E2E
  - Semgrep
  - Trivy
  - CodeQL on PR
- nightly security workflow still runs heavy scans regardless of degrade mode

Bootstrap example:

```bash
./scripts/bootstrap/project.sh my-service node \
  --org Forge-Space \
  --actions-cap-minutes 20000
```

Initialize Actions budget variables for an org:

```bash
./scripts/bootstrap/actions-org-setup.sh \
  --org Forge-Space \
  --actions-cap-minutes 20000
```

### Related Guides

1. [Organization Setup](docs/guides/organization-setup.md)
2. [Actions Limits Strategy](docs/guides/actions-limits-strategy.md)

## � Documentation

For complete documentation, see our **[Documentation Hub](docs/README.md)** which includes:

- **[Project Context](docs/project/PROJECT_CONTEXT.MD)** - Complete project guide and context
- **[Implementation Reports](docs/reports/)** - Integration and analysis reports
- **[Pattern Documentation](docs/patterns/)** - All pattern documentation
- **[Architecture Decisions](docs/architecture-decisions/)** - System design decisions
- **[User Guides](docs/guides/)** - Deployment and user journey guides
- **[MCP Context Server](docs/guides/MCP_CONTEXT_SERVER.md)** - Setup and IDE integration for the Forge Space context MCP server
- **[VSCode Extension](patterns/ide-extensions/vscode/README.md)** - Pattern discovery, scaffolding, and compliance validation in VSCode
- **[Development Standards](docs/standards/)** - Coding and security standards

## 🚀 Quick Start

### 1. Install Forge Patterns

```bash
npm install @forgespace/core
```

Published on npm as
[`@forgespace/core`](https://www.npmjs.com/package/@forgespace/core).

### 2. Integrate into Your Project

```bash
# Navigate to your project directory
cd /path/to/your-project
# Use the automated integration CLI
npx forge-patterns integrate

# Or use individual integration commands
npx forge-patterns integrate --project=mcp-gateway
npx forge-patterns integrate --project=siza-mcp
npx forge-patterns integrate --project=siza
```

`--project=siza-mcp` is the current integration CLI alias for the `ui-mcp`
server in this repo.

## Community

- [Documentation hub](https://docs.forgespace.co/docs)
- [GitHub Discussions](https://github.com/orgs/Forge-Space/discussions)

## GitHub Workflow

This repository follows the shared Forge Space GitHub work-management baseline:

- Discussions for ideas, RFCs, Q&A, and announcements
- Issues for actionable delivery work
- Projects for roadmap visibility and cross-repo reporting

See [Forge-Space/.github `GOVERNANCE.md`](https://github.com/Forge-Space/.github/blob/main/GOVERNANCE.md)
for the org-wide contract.

## Funding Ops

The repo includes an NLnet packet generator for the `mcp-gateway` funding lane.
Project facts stay in `ops/funding/nlnet/project.json`, while personal/contact
details belong in the ignored `ops/funding/nlnet/applicant.local.json`.

```bash
cp ops/funding/nlnet/applicant.local.example.json ops/funding/nlnet/applicant.local.json
npm run funding:nlnet:render
npm run funding:nlnet:check
```

Generated artifacts land in `ops/funding/nlnet/generated/` and stay redacted for
workflow-safe issue updates and browser-assisted handoff.
- [Issue tracker](https://github.com/Forge-Space/core/issues)

## 📁 Repository Structure

```bash

forge-patterns/
├── .github/
│   ├── workflows/          # CI/CD workflow templates
│   └── templates/          # GitHub templates (PR, issues)
├── patterns/
│   ├── code-quality/       # ESLint, Prettier configurations
│   ├── config/            # Centralized configuration management
│   ├── docker/            # Docker and containerization patterns
│   ├── feature-toggles/   # 🎛️ Centralized feature toggle system
│   ├── git/               # Git hooks and workflows
│   ├── mcp-gateway/       # MCP Gateway patterns (security, performance)
│   ├── mcp-servers/       # MCP Server patterns (AI providers, streaming)
│   ├── security/          # Security patterns (authentication, middleware)
│   └── shared-infrastructure/ # Shared infrastructure patterns (optimization)
├── docs/                   # 📚 Comprehensive documentation
│   ├── architecture/       # Architecture decisions and summaries
│   ├── architecture-decisions/ # ADRs for system design
│   ├── guides/            # User guides and deployment playbooks
│   ├── standards/         # Development and security standards
│   └── reports/           # Implementation and analysis reports
├── test/                   # 🧪 Comprehensive test suites
│   ├── feature-toggle-validation.js # Feature toggle system tests
│   ├── cross-project-integration.js # Cross-project integration tests
│   └── performance-benchmark.js # Performance benchmarking
├── scripts/
│   ├── forge-features      # 🎛️ CLI tool for feature management
│   ├── integrate.js        # Automated integration script
│   ├── apply-readme-branding.sh     # Forge Space README header (CDN wordmark)
│   ├── apply-readme-branding-all.sh # Run branding for all Forge Space projects
│   ├── security/          # Security validation scripts
│   └── bootstrap/         # Project bootstrap scripts
├── src/                   # TypeScript source files
├── test/                  # 🧪 Comprehensive test suites
├── package.json           # Package configuration
└── README.md             # This file
```

## 🔧 Available Patterns

### 🎛️ Centralized Feature Toggle System

**NEW**: Cross-project feature management with unified control

```bash
# Enable global features
forge-features enable global.debug-mode
forge-features enable global.beta-features

# Enable project-specific features
forge-features enable mcp-gateway.rate-limiting
forge-features enable forge-space-ui.rate-limiting
forge-features enable forge-space-mcp.ai-chat
forge-features enable forge-space-ui.dark-mode

# Check feature status
forge-features status --global
forge-features status --project=mcp-gateway
```

**Features**:

- Global and project-specific feature namespaces
- CLI tool for feature management
- Real-time feature updates
- Cross-project consistency

### Code Quality Patterns

#### ESLint Configuration

```javascript
// Base ESLint config for TypeScript projects
module.exports = {
  root: true,
  extends: ['eslint:recommended', '@typescript-eslint/recommended', 'prettier'],
  // ... comprehensive rules
};
```

#### Prettier Configuration
```json
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always",
  "endOfLine": "lf"
}
```

### Docker Patterns

#### **NEW**: High-Efficiency Docker Standards
```yaml
# Three-state service model with sleep/wake architecture
services:
  [service-name]:
    resources:
      memory: "512M"
      cpu: "0.5"
      memory_reservation: "256M"
    sleep_policy:
      enabled: true
      idle_timeout: 300
      priority: "normal"
    auto_start: false
```

#### Multi-stage Dockerfile
```dockerfile
# Build stage
FROM node:22-alpine AS builder
# ... build process

# Production stage
FROM node:22-alpine AS runtime
# ... optimized production image
```

#### Docker Compose Development
```yaml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
    command: npm run dev
```

### Test Coverage Patterns

#### Jest Configuration (TypeScript)
```javascript
module.exports = {
  collectCoverageFrom: ['src/**/*.ts'],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
};
```

#### Codecov Configuration
```yaml
codecov:
  coverage:
    status:
      project:
        default:
          target: 80%
          threshold: 1%
```

### Git Workflow Patterns

#### Pre-commit Hook
```bash
#!/bin/bash
# Comprehensive pre-commit validation
echo "🚀 Running Forge Space pre-commit validations..."
# Security validation, linting, testing, etc.
```

#### Conventional Commits
```bash
# Enforces conventional commit format
# feat, fix, docs, style, ref

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Forge-Space](https://github.com/Forge-Space)
- **Source:** [Forge-Space/core](https://github.com/Forge-Space/core)
- **License:** MIT
- **Homepage:** https://github.com/Forge-Space/core

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-forge-space-core
- Seller: https://agentstack.voostack.com/s/forge-space
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.