@venizia/ignis-docs 0.0.6-3 → 0.0.7-0

package/README.md

@@ -1,9 +1,42 @@
-# @venizia/ignis-docs
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/@venizia/ignis-docs.svg)](https://www.npmjs.com/package/@venizia/ignis-docs)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+# :fire: IGNIS - @venizia/ignis-docs
 
-Documentation and **MCP (Model Context Protocol) Server** for the **Ignis Framework**. The MCP server allows AI assistants to access Ignis documentation in real-time.
+**Documentation site and MCP server for the Ignis Framework**
+
+[![npm](https://img.shields.io/npm/v/@venizia/ignis-docs.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@venizia/ignis-docs)
+[![License](https://img.shields.io/badge/License-MIT-3DA639.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-8B5CF6.svg?style=flat-square)](https://modelcontextprotocol.io/)
+
+VitePress-powered documentation site and an MCP server with 11 tools that gives AI assistants real-time access to Ignis knowledge -- search docs, browse source code, and verify dependencies.
+
+[Installation](#installation) &#8226; [MCP Setup](#mcp-server-setup) &#8226; [Available Tools](#available-mcp-tools) &#8226; [Online Docs](https://venizia-ai.github.io/ignis)
+
+</div>
+
+---
+
+## Highlights
+
+| | Feature | |
+| :---: | :--- | :--- |
+| **1** | **11 MCP Tools** | Search docs, browse code, verify deps from any AI assistant |
+| **2** | **Fuzzy Search** | Fuse.js-powered search across all documentation |
+| **3** | **VitePress Site** | Full-featured docs with guides, API references, and tutorials |
+| **4** | **CLI Binary** | Ships as `ignis-docs-mcp` for easy MCP integration |
+
+---
+
+## Features
+
+- **VitePress Documentation Site** -- Full-featured docs with guides, API references, tutorials, and best practices
+- **MCP Server** -- 11 tools for AI assistants to search docs, browse source code, and verify dependencies
+- **Fuzzy Search** -- Fuse.js-powered search across all documentation (title weight 0.7, content weight 0.3)
+- **GitHub Integration** -- Browse project files, search code, and verify dependency versions directly from AI tools
+- **CLI Binary** -- Ships as `ignis-docs-mcp` for easy integration with Claude Desktop and other MCP-compatible clients
+
+---
 
 ## Installation
 
@@ -13,7 +46,11 @@ bun add @venizia/ignis-docs
 npm install @venizia/ignis-docs
 ```
 
-## MCP Server Usage
+---
+
+## MCP Server Setup
+
+### Claude Desktop
 
 Add to your Claude Desktop config (`claude_desktop_config.json`):
 
@@ -28,432 +65,132 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
 }
 ```
 
-You can also `npx` for alternative
-
-## Available MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| **search** | Search documentation by keyword |
-| **getDocContent** | Get full content of a document |
-| **listDocs** | List all available documents |
-| **listCategories** | List documentation categories |
-| **getDocMetadata** | Get document metadata |
-
-## About Ignis
-
-Ignis brings together the structured, enterprise development experience of **LoopBack 4** with the blazing speed and simplicity of **Hono** - giving you the best of both worlds.
+Alternatively, use `npx`:
 
-## Documentation
-
-- [Ignis Repository](https://github.com/venizia-ai/ignis)
-- [MCP Server Guide](https://github.com/venizia-ai/ignis/blob/main/packages/docs/wiki/get-started/mcp-docs-server.md)
-- [Main Documentation](https://github.com/venizia-ai/ignis/blob/main/packages/docs/wiki/index.md)
-
-## License
-
-MIT
-
----
-
-## MCP Docs Server | PROMP REQUEST: 
-
-**Question:** With Bun runtime + package management, create a monorepo project, "packages" is root folder of contain another project folder. Inside "packages" have two folder "be" and "fe". Just implement be with best practice ignis framework.
-
----
-## Plan: Create Bun Workspace Monorepo with Production-Ready Ignis Backend
-
-## User Requirements ✅
-- **Backend Scope**: Production Starter Kit (CRUD API + Authentication + Components)
-- **Components**: Swagger (API Docs), Health Check, Authentication (JWT)
-- **Frontend**: Empty placeholder with basic package.json
-- **Architecture**: Follow Ignis best practices
-
----
-
-## Implementation Plan
+```json
+{
+  "mcpServers": {
+    "ignis-docs": {
+      "command": "npx",
+      "args": ["@venizia/ignis-docs@latest"]
+    }
+  }
+}
+```
 
-### 1. Root Monorepo Setup
+### Claude Code
 
-**Files to create:**
-- `package.json` - Root workspace configuration
-- `.gitignore` - Ignore node_modules, dist, .env files
-- `README.md` - Project documentation
+Add to your Claude Code MCP settings:
 
-**Root package.json structure:**
 ```json
 {
-  "name": "ignis-monorepo",
-  "version": "1.0.0",
-  "private": true,
-  "workspaces": ["packages/*"],
-  "scripts": {
-    "be:dev": "bun --cwd packages/be run server:dev",
-    "be:build": "bun --cwd packages/be run build",
-    "be:lint": "bun --cwd packages/be run lint"
+  "mcpServers": {
+    "ignis-docs": {
+      "command": "bunx",
+      "args": ["@venizia/ignis-docs@latest"]
+    }
   }
 }
 ```
 
 ---
 
-### 2. Backend Package Structure (`packages/be/`)
+## Available MCP Tools
 
-**Directory structure:**
-```
-packages/be/
-├── package.json
-├── tsconfig.json
-├── .prettierrc.mjs
-├── .prettierignore
-├── eslint.config.mjs
-├── .env.example
-├── scripts/
-│   └── clean.sh
-└── src/
-    ├── index.ts              # Entry point
-    ├── application.ts        # Main application class
-    ├── migration.ts          # Drizzle migration config
-    ├── controllers/
-    │   ├── hello.controller.ts
-    │   └── todo.controller.ts
-    ├── services/
-    │   └── authentication.service.ts
-    ├── repositories/
-    │   └── todo.repository.ts
-    ├── datasources/
-    │   └── postgres.datasource.ts
-    └── models/
-        └── todo.model.ts
-```
+### Documentation Tools
+
+| Tool | Description |
+| --- | --- |
+| **searchDocs** | Search documentation by keyword with fuzzy matching |
+| **getDocContent** | Get the full content of a specific document |
+| **listDocs** | List all available documentation pages |
+| **listCategories** | List documentation categories and their structure |
+| **getDocMetadata** | Get metadata (title, path, category) for a document |
+| **getPackageOverview** | Get an overview of a specific Ignis package |
 
-**Key decisions:**
-- PostgreSQL for database (as recommended in Ignis docs)
-- Todo CRUD as example implementation
-- JWT authentication with custom AuthenticationService
-- All three components: Swagger, Health Check, Authentication
+### GitHub Tools
+
+| Tool | Description |
+| --- | --- |
+| **searchCode** | Search the Ignis source code by keyword |
+| **listProjectFiles** | List files in a specific directory of the repository |
+| **viewSourceFile** | View the contents of a source file |
+| **verifyDependencies** | Check dependency versions and compatibility |
 
 ---
 
-### 3. Backend Dependencies
+## Documentation Site
 
-**Production dependencies:**
-```bash
-bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis dotenv-flow
-bun add drizzle-orm drizzle-zod pg lodash
-```
+### Development
 
-**Development dependencies:**
 ```bash
-bun add -d typescript @types/bun @venizia/dev-configs tsc-alias
-bun add -d drizzle-kit @types/pg @types/lodash
-```
+# Start dev server
+bun run docs:dev
 
----
+# Build static site
+bun run docs:build
 
-### 4. Configuration Files
-
-**tsconfig.json:**
-- Extend from `@venizia/dev-configs/tsconfig.common.json`
-- Configure path aliases: `@/*` → `src/*`
-- Output to `dist/`
-
-**.prettierrc.mjs:**
-- Import from `@venizia/dev-configs`
-
-**eslint.config.mjs:**
-- Import from `@venizia/dev-configs`
-
-**.env.example:**
-```env
-# Application
-HOST=0.0.0.0
-PORT=3000
-APP_ENV_APPLICATION_NAME=ignis-backend
-
-# Database
-APP_ENV_POSTGRES_HOST=localhost
-APP_ENV_POSTGRES_PORT=5432
-APP_ENV_POSTGRES_USERNAME=postgres
-APP_ENV_POSTGRES_PASSWORD=your_password
-APP_ENV_POSTGRES_DATABASE=ignis_db
-
-# Authentication (REQUIRED - Generate strong secrets!)
-APP_ENV_APPLICATION_SECRET=your-strong-application-secret-here
-APP_ENV_JWT_SECRET=your-strong-jwt-secret-here
-APP_ENV_JWT_EXPIRES_IN=86400
+# Preview production build
+bun run docs:preview
 ```
 
----
-
-### 5. Core Implementation Files
-
-#### `src/application.ts`
-**Features:**
-- Register PostgresDataSource
-- Register TodoRepository
-- Register TodoController, HelloController
-- Register AuthenticationService
-- Register all 3 components: HealthCheckComponent, SwaggerComponent, AuthenticateComponent
-- Register JWTAuthenticationStrategy
-- Configure app with base path `/api`
-
-#### `src/models/todo.model.ts`
-**Schema:**
-- `id` (UUID, auto-generated)
-- `title` (text, required)
-- `description` (text, optional)
-- `isCompleted` (boolean, default false)
-- `createdAt`, `modifiedAt` (timestamps, auto-generated)
-
-#### `src/datasources/postgres.datasource.ts`
-**Features:**
-- Connect to PostgreSQL using environment variables
-- Register Todo model schema
-- Implement connect/disconnect lifecycle
-
-#### `src/repositories/todo.repository.ts`
-**Features:**
-- Extend `DefaultCRUDRepository<TTodoSchema>`
-- Inject PostgresDataSource
-
-#### `src/controllers/todo.controller.ts`
-**Features:**
-- Use `ControllerFactory.defineCrudController()` for auto-generated CRUD endpoints
-- Base path: `/todos`
-- All operations protected by JWT (optional - can be added later)
-
-#### `src/controllers/hello.controller.ts`
-**Features:**
-- Simple GET `/hello` endpoint
-- Returns `{ message: "Hello, World!" }`
-- OpenAPI schema with Zod
-
-#### `src/services/authentication.service.ts`
-**Features:**
-- Implement `IAuthService` interface
-- `signIn()` method with hardcoded test credentials (test_username / test_password)
-- Generate JWT using JWTTokenService
-- TODO comments for production implementation (database lookup, password hashing)
-
-#### `src/migration.ts`
-**Features:**
-- Drizzle Kit configuration
-- Point to todo.model.ts
-- Use PostgreSQL dialect
-- Connection from environment variables
-
-#### `src/index.ts`
-**Features:**
-- Import dotenv-flow
-- Create Application instance
-- Start server
-
----
-
-### 6. Frontend Package Structure (`packages/fe/`)
+### Structure
 
-**Minimal setup:**
 ```
-packages/fe/
-├── package.json
-└── README.md
+wiki/
+├── guides/              # Getting started, core concepts, tutorials
+├── references/          # API documentation
+│   ├── base/            # BaseApplication, BaseController, BaseEntity, etc.
+│   ├── components/      # HealthCheck, Swagger, Auth, Mail, SocketIO, etc.
+│   ├── helpers/         # Logger, Redis, Queue, Storage, Crypto, etc.
+│   └── utilities/       # Parse, Date, Promise, Performance utilities
+├── best-practices/      # Architecture, security, performance, code style
+└── changelogs/          # Version release notes
 ```
 
-**package.json:**
-```json
-{
-  "name": "@ignis-monorepo/fe",
-  "version": "1.0.0",
-  "private": true,
-  "description": "Frontend application - framework to be determined"
-}
-```
+### Online Documentation
 
-**README.md:**
-```markdown
-# Frontend Application
+[https://venizia-ai.github.io/ignis](https://venizia-ai.github.io/ignis)
 
-This folder is prepared for the frontend application.
+---
 
-## Next Steps
-- Choose your framework (React, Vue, Svelte, etc.)
-- Run framework setup command
-- Configure to work with backend at http://localhost:3000/api
-```
+## MCP Server Development
 
----
+```bash
+# Development mode
+bun run mcp:dev
 
-### 7. Scripts and Utilities
+# Build MCP server
+bun run mcp:build
 
-**packages/be/scripts/clean.sh:**
-- Remove `dist/`, `*.tsbuildinfo`, `.eslintcache`
-- Remove `artifact.zip`
+# Start MCP server
+bun run mcp:start
 
-**packages/be/package.json scripts:**
-```json
-{
-  "lint": "bun run eslint && bun run prettier:cli",
-  "lint:fix": "bun run eslint --fix && bun run prettier:fix",
-  "prettier:cli": "prettier \"**/*.{js,ts}\" -l",
-  "prettier:fix": "bun run prettier:cli --write",
-  "eslint": "eslint --report-unused-disable-directives .",
-  "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
-  "clean": "sh ./scripts/clean.sh",
-  "rebuild": "bun run clean && bun run build",
-  "migrate:dev": "NODE_ENV=development drizzle-kit push --config=src/migration.ts",
-  "generate-migration:dev": "NODE_ENV=development drizzle-kit generate --config=src/migration.ts",
-  "preserver:dev": "bun run rebuild",
-  "server:dev": "NODE_ENV=development bun .",
-  "server:prod": "NODE_ENV=production bun ."
-}
+# Clean + rebuild
+bun run mcp:rebuild
 ```
 
----
+### Configuration
 
-### 8. Post-Setup Instructions
-
-**After implementation, user needs to:**
-
-1. **Create PostgreSQL database:**
-   ```bash
-   psql -U postgres
-   CREATE DATABASE ignis_db;
-   \q
-   ```
-
-2. **Copy .env.example to .env and configure:**
-   ```bash
-   cd packages/be
-   cp .env.example .env
-   # Edit .env with your database credentials and secrets
-   ```
-
-3. **Generate strong secrets:**
-   ```bash
-   # Use these commands to generate secrets:
-   openssl rand -base64 32  # For APP_ENV_APPLICATION_SECRET
-   openssl rand -base64 32  # For APP_ENV_JWT_SECRET
-   ```
-
-4. **Install dependencies:**
-   ```bash
-   bun install
-   ```
-
-5. **Run database migration:**
-   ```bash
-   bun run be:dev  # This will run migration automatically via preserver:dev
-   ```
-
-6. **Test the API:**
-   - Health check: `http://localhost:3000/health`
-   - API docs: `http://localhost:3000/doc/explorer`
-   - Hello endpoint: `http://localhost:3000/api/hello`
-   - Sign in: `POST http://localhost:3000/api/auth/sign-in` with `{"identifier": {"value": "test_username"}, "credential": {"value": "test_password"}}`
-   - Todos CRUD: `http://localhost:3000/api/todos`
+| Setting | Default | Description |
+| --- | --- | --- |
+| `snippetLength` | `320` | Max characters per search result snippet |
+| `defaultLimit` | `10` | Default number of search results |
+| `maxLimit` | `50` | Maximum number of search results |
+| `searchThreshold` | `0.4` | Fuse.js fuzzy match threshold (0 = exact, 1 = loose) |
+| `repo` | `VENIZIA-AI/ignis` | GitHub repository for source code tools |
 
 ---
 
-### 9. Available Endpoints
-
-After setup, the following endpoints will be available:
-
-| Method | Path | Description | Auth Required |
-|--------|------|-------------|---------------|
-| `GET` | `/health` | Health check | No |
-| `POST` | `/health/ping` | Ping-pong test | No |
-| `GET` | `/doc/explorer` | Swagger UI (Scalar) | No |
-| `GET` | `/doc/openapi.json` | OpenAPI spec | No |
-| `GET` | `/api/hello` | Hello world | No |
-| `POST` | `/api/auth/sign-in` | JWT login | No |
-| `GET` | `/api/todos` | List todos | No* |
-| `POST` | `/api/todos` | Create todo | No* |
-| `GET` | `/api/todos/:id` | Get todo | No* |
-| `PATCH` | `/api/todos/:id` | Update todo | No* |
-| `DELETE` | `/api/todos/:id` | Delete todo | No* |
-
-*Note: Todo endpoints can be easily protected with JWT by adding `authStrategies: [Authentication.STRATEGY_JWT]` to route configs*
-
----
+## Related Links
 
-### 10. Critical Files to Create
-
-**Root level:**
-1. `package.json` - Workspace config
-2. `.gitignore` - Git ignore patterns
-3. `README.md` - Project documentation
-
-**packages/be/:**
-1. `package.json` - Backend dependencies and scripts
-2. `tsconfig.json` - TypeScript configuration
-3. `.prettierrc.mjs` - Prettier config
-4. `.prettierignore` - Prettier ignore patterns
-5. `eslint.config.mjs` - ESLint config
-6. `.env.example` - Environment variable template
-7. `scripts/clean.sh` - Cleanup script
-8. `src/index.ts` - Entry point
-9. `src/application.ts` - Main application class
-10. `src/migration.ts` - Database migration config
-11. `src/models/todo.model.ts` - Todo model
-12. `src/datasources/postgres.datasource.ts` - Database connection
-13. `src/repositories/todo.repository.ts` - Todo data access
-14. `src/controllers/todo.controller.ts` - Todo API endpoints
-15. `src/controllers/hello.controller.ts` - Hello endpoint
-16. `src/services/authentication.service.ts` - Auth logic
-
-**packages/fe/:**
-1. `package.json` - Frontend package placeholder
-2. `README.md` - Frontend setup instructions
+- [Ignis Framework](https://github.com/VENIZIA-AI/ignis) -- Main repository
+- [Online Documentation](https://venizia-ai.github.io/ignis) -- Full documentation site
+- [MCP Server Guide](https://github.com/VENIZIA-AI/ignis/blob/main/packages/docs/wiki/get-started/mcp-docs-server.md) -- Detailed setup guide
+- [Model Context Protocol](https://modelcontextprotocol.io/) -- MCP specification
 
 ---
 
-## Architecture Summary
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     HTTP Requests                           │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       ▼
-         ┌─────────────────────────┐
-         │  Components Layer       │
-         │  • HealthCheckComponent │
-         │  • SwaggerComponent     │
-         │  • AuthenticateComponent│
-         └────────────┬────────────┘
-                      │
-                      ▼
-         ┌─────────────────────────┐
-         │  Controllers Layer      │
-         │  • HelloController      │
-         │  • TodoController       │
-         │  • (Auth auto-registered)│
-         └────────────┬────────────┘
-                      │
-                      ▼
-         ┌─────────────────────────┐
-         │  Services Layer         │
-         │  • AuthenticationService│
-         │  • (Business logic)     │
-         └────────────┬────────────┘
-                      │
-                      ▼
-         ┌─────────────────────────┐
-         │  Repositories Layer     │
-         │  • TodoRepository       │
-         └────────────┬────────────┘
-                      │
-                      ▼
-         ┌─────────────────────────┐
-         │  DataSources Layer      │
-         │  • PostgresDataSource   │
-         └────────────┬────────────┘
-                      │
-                      ▼
-         ┌─────────────────────────┐
-         │     PostgreSQL DB       │
-         └─────────────────────────┘
-```
+## License
 
-This follows Ignis layered architecture best practices with clear separation of concerns.
+MIT

package/dist/mcp-server/common/config.d.ts

@@ -1,13 +1,8 @@
-/**
- * Centralized configuration for the Ignis MCP Documentation Server.
- * All tool constants and settings are defined here for easy maintenance.
- */
 export declare class MCPConfigs {
     static readonly server: {
         readonly name: "ignis-docs";
         readonly version: "0.0.1";
     };
-    /** Runtime-configurable branch (set via CLI argument) */
     private static _branch;
     static readonly github: {
         apiBase: string;
@@ -16,45 +11,29 @@ export declare class MCPConfigs {
         repoPath: string;
         repoName: string;
         userAgent: string;
-        /** Get current branch (configurable at runtime) */
         readonly branch: string;
     };
-    /**
-     * Set the GitHub branch to use for fetching source code.
-     * Call this before starting the server.
-     * @param branch - Branch name (e.g., 'main', 'develop', 'feature/xyz')
-     */
     static setBranch(opts: {
         branch: string;
     }): void;
     static readonly search: {
-        /** Maximum characters for content snippet in search results */
         snippetLength: number;
-        /** Default number of results to return */
         defaultLimit: number;
-        /** Maximum allowed results per search */
         maxLimit: number;
-        /** Minimum query length required */
         minQueryLength: number;
     };
     static readonly codeSearch: {
-        /** Default number of results to return */
         defaultLimit: number;
-        /** Maximum allowed results per search (GitHub API limit) */
         maxLimit: number;
-        /** Minimum query length required */
         minQueryLength: number;
-        /** Rate limit warning threshold */
         rateLimitWarningThreshold: number;
     };
     static readonly fuse: {
         includeScore: boolean;
-        /** Lower threshold = stricter matching (0.0 = exact, 1.0 = match anything) */
         threshold: number;
         minMatchCharLength: number;
         findAllMatches: boolean;
         ignoreLocation: boolean;
-        /** Search field weights: title matches are prioritized over content */
         keys: {
             name: string;
             weight: number;

package/dist/mcp-server/common/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../mcp-server/common/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU;IAIrB,MAAM,CAAC,QAAQ,CAAC,MAAM;;;MAAqD;IAM3E,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,OAAO,CAAkB;IAExC,MAAM,CAAC,QAAQ,CAAC,MAAM;;;;;;;QAQpB,mDAAmD;yBACrC,MAAM;MAGpB;IAEF;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;IAOzC,MAAM,CAAC,QAAQ,CAAC,MAAM;QACpB,+DAA+D;;QAE/D,0CAA0C;;QAE1C,yCAAyC;;QAEzC,oCAAoC;;MAEpC;IAKF,MAAM,CAAC,QAAQ,CAAC,UAAU;QACxB,0CAA0C;;QAE1C,4DAA4D;;QAE5D,oCAAoC;;QAEpC,mCAAmC;;MAEnC;IAKF,MAAM,CAAC,QAAQ,CAAC,IAAI;;QAElB,8EAA8E;;;;;QAK9E,uEAAuE;;;;;MAKvE;CACH"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../mcp-server/common/config.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,MAAM;;;MAAqD;IAE3E,OAAO,CAAC,MAAM,CAAC,OAAO,CAAkB;IAExC,MAAM,CAAC,QAAQ,CAAC,MAAM;;;;;;;yBAQN,MAAM;MAGpB;IAEF,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;IAIzC,MAAM,CAAC,QAAQ,CAAC,MAAM;;;;;MAKpB;IAEF,MAAM,CAAC,QAAQ,CAAC,UAAU;;;;;MAKxB;IAEF,MAAM,CAAC,QAAQ,CAAC,IAAI;;;;;;;;;;MAWlB;CACH"}