@mofaggolhoshen/dev-assist-mcp 1.0.5 → 1.0.6

package/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+This file helps AI coding agents become productive quickly in this repository.
+
+## Scope
+
+- Applies to the whole repository.
+- Prefer minimal, targeted changes over broad refactors.
+- Keep existing public tool names and response shapes stable unless explicitly requested.
+
+## Quick Start Commands
+
+- Install: `npm install`
+- Build: `npm run build`
+- Dev server (stdio MCP): `npm run dev`
+- Run compiled server: `npm start`
+- Test: `npm test`
+
+## Project Map
+
+- `src/index.ts`: MCP server bootstrap and tool registration.
+- `src/tools/types.ts`: shared `Tool` contract.
+- `src/tools/registry.ts`: tool registration and lookup.
+- `src/tools/fs/`: filesystem tools and path safety.
+- `src/tools/knowledge/`: snippet/template/concept/setup tools.
+- `src/tools/intelligence/`: project analysis tooling.
+- `src/storage/markdownKnowledgeStore.ts`: markdown loading, Fuse ranking, filtering.
+- `src/schemas/markdownKnowledge.ts`: frontmatter validation schemas.
+- `src/shared/response.ts`: `textResponse` and `errorResponse` helpers.
+- `snippets/`: reusable snippet knowledge content.
+- `content/`: concepts, templates, and setup docs used by knowledge tools.
+- `tests/`: Jest test suite.
+
+## Coding Conventions
+
+- Runtime source is ESM (`type: module`, `NodeNext` in tsconfig).
+- Keep `.js` import suffixes in TypeScript source files.
+- Tests compile as CommonJS via `tsconfig.test.json`; Jest maps local `.js` imports.
+- Validate inputs with Zod schemas for every tool.
+- Return MCP responses using `textResponse(...)` (or `errorResponse(...)`) from `src/shared/response.ts`.
+- Prefer structured JSON string payloads for machine-consumable tool output.
+
+## Safety Rules
+
+- For filesystem access, use `resolveSafePath` from `src/tools/fs/safePath.ts`.
+- Never bypass project-root boundary checks.
+- Keep tool names unique in the registry.
+
+## Common Agent Tasks
+
+### Add a new MCP tool
+
+1. Create `src/tools/<category>/<toolName>.ts` implementing the `Tool` interface.
+2. Define a Zod `inputSchema` and `execute` handler.
+3. Register the tool in `src/index.ts`.
+4. Add tests in `tests/`.
+5. Run `npm test` and `npm run build`.
+
+### Add or update snippet content
+
+1. Edit/create markdown files under `snippets/` with valid YAML frontmatter.
+2. Follow schema expectations in `src/schemas/markdownKnowledge.ts`.
+3. Note: frontmatter dates may be parsed as Date objects; schema normalization handles `updatedAt`.
+4. Run `npm test`.
+
+## Documentation Links (Read Before Large Changes)
+
+- Project overview and examples: [README](README.md)
+- Product requirements: [PRD v2](docs/PRD-v2.md)
+- Implementation roadmap: [Implementation Plan](docs/Implementation-Plan.md)
+- Publishing workflow: [Publish Guide](docs/Publish.md)
+- Usage examples: [examples](examples/)

package/README.md

@@ -1,55 +1,64 @@
-# DevAssist MCP Server
+# DevAssist MCP
 
-stdio-based MCP server in TypeScript that exposes project file access, reusable snippets, and lightweight project analysis tools for AI clients.
+Production-ready developer assistance through Model Context Protocol (MCP).
 
-## Quick Start
+DevAssist MCP is an AI-first developer knowledge server that provides curated snippets, setup guides, architecture templates, concept explanations, and project analysis for modern engineering workflows.
 
-1. Install dependencies:
+## Why DevAssist MCP
 
-```bash
-npm install
-```
+AI-generated code is often incomplete, outdated, or missing production context. DevAssist MCP improves output quality by returning structured, version-aware, reusable engineering knowledge instead of generic examples.
 
-1. Build the server:
+## Key Capabilities
 
-```bash
-npm run build
-```
+- MCP-compatible stdio server
+- Production-ready, curated engineering content
+- Framework and version-aware retrieval
+- Deterministic ranking with confidence signals
+- Explain mode for engineering concepts
+- Setup generation for common backend scenarios
+- Template retrieval for architecture starters
+- File-system and project analysis utility tools
+- Structured responses optimized for AI clients
+
+## Supported Domains
 
-1. Run locally (compiled):
+- Authentication: JWT, JWE, role-based authorization, refresh-token rotation
+- Resilience: retry, timeout, circuit breaker, fallback, bulkhead
+- Observability: Serilog, OpenTelemetry tracing, structured logging
+- Architecture: Clean Architecture, CQRS, DDD, repository patterns
+- Messaging: MassTransit, RabbitMQ, outbox, saga state machine
+- Caching: Redis distributed cache, cache-aside
+
+## Installation
+
+### npm
 
 ```bash
-npm start
+npm install @mofaggolhoshen/dev-assist-mcp
 ```
 
-1. Or run in development mode:
+### Run with npx
 
 ```bash
-npm run dev
+npx -y @mofaggolhoshen/dev-assist-mcp
 ```
 
-## VS Code MCP Configuration
-
-You can run the MCP server in VS Code either from this repository or from the published npm package.
+## MCP Client Integration
 
-Local workspace setup:
+### Claude Desktop
 
 ```json
 {
-  "servers": {
-    "dev-assist": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["dist/index.js"],
-      "cwd": "${workspaceFolder}"
+  "mcpServers": {
+    "dev-assist-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mofaggolhoshen/dev-assist-mcp"]
     }
   }
 }
 ```
 
-Build once with `npm run build`, then VS Code can launch the server through stdio.
-
-Published npm package setup:
+### VS Code MCP
 
 ```json
 {
@@ -63,38 +72,181 @@ Published npm package setup:
 }
 ```
 
-This package-based setup is useful when you do not want to build the server from source inside each workspace.
+## MCP Tools
+
+### Knowledge Tools (PRD-aligned)
 
-## Tool Catalog
+| Tool | Purpose |
+|---|---|
+| search_snippet | Search reusable engineering snippets with optional filters |
+| get_snippet | Retrieve a detailed snippet by name |
+| get_template | Return complete implementation templates |
+| explain_concept | Explain engineering concepts with practical guidance |
+| generate_setup | Generate production-ready setup guidance |
 
-| Tool | Description | Input |
-| --- | --- | --- |
-| `ping` | Returns pong to verify the server is reachable | `{}` |
-| `list_files` | Lists files recursively under a directory | `{ path?: string }` |
-| `read_file` | Reads a text file from the workspace | `{ path: string }` |
-| `search_code` | Keyword search across text-like files | `{ keyword: string, path?: string }` |
-| `get_snippet` | Returns a named snippet from `snippets/` | `{ name: string }` |
-| `analyze_project` | Detects language/framework/architecture hints | `{ path?: string }` |
+### Utility Tools
 
-## Adding Custom Tools
+| Tool | Purpose |
+|---|---|
+| list_files | List files under a project path |
+| read_file | Read a text file from project scope |
+| search_code | Search keyword matches in project text files |
+| analyze_project | Detect language, framework, architecture, and container hints |
 
-1. Create a new tool module under `src/tools/...` implementing the `Tool` interface from `src/tools/types.ts`.
-2. Define `name`, `description`, `inputSchema` (Zod), and `execute`.
-3. Register the tool in `src/index.ts` using `registry.register(yourTool)`.
-4. Rebuild with `npm run build`.
+## Example Prompts
 
-## Snippet Authoring
+- Give me JWT authentication setup for ASP.NET 9
+- Show Polly retry with exponential backoff
+- Explain circuit breaker pattern
+- Get clean architecture template
+- Analyze this repository structure
 
-Add JSON files under `snippets/` using this schema:
+## Example Structured Response
 
 ```json
 {
-  "name": "snippet-name",
-  "title": "Human Friendly Title",
-  "language": "csharp",
-  "description": "What this snippet does",
-  "code": "...source code..."
+  "query": "jwt authentication asp.net 9",
+  "filters": {
+    "framework": ".net",
+    "version": "9",
+    "category": "auth",
+    "difficulty": "medium",
+    "limit": 10
+  },
+  "total": 1,
+  "results": [
+    {
+      "id": "jwt-setup-dotnet9",
+      "title": "JWT Authentication ASP.NET 9",
+      "framework": ".net",
+      "version": "9",
+      "difficulty": "medium",
+      "confidence": "high",
+      "reasons": ["framework-match", "version-match", "tag-match"]
+    }
+  ]
 }
 ```
 
-The `name` must match `[A-Za-z0-9-]+` because it maps to `snippets/{name}.json`.
+## Architecture (MVP)
+
+```txt
+AI Client (Copilot / Cursor / Claude)
+            |
+            v
+DevAssist MCP Server (TypeScript MCP SDK)
+            |
+            v
+Catalog + Ranking + Validation Layers
+            |
+            v
+Markdown Knowledge Store (snippets, templates, concepts, setups)
+```
+
+## Repository Layout
+
+```txt
+src/
+  tools/
+  storage/
+  ranking/
+  catalog/
+  content/
+snippets/
+content/
+  concepts/
+  templates/
+  setups/
+examples/
+docs/
+tests/
+```
+
+## Development
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Run in development
+
+```bash
+npm run dev
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run tests
+
+```bash
+npm run test
+```
+
+## Content Authoring Format
+
+Knowledge content uses Markdown with YAML frontmatter.
+
+### Snippet frontmatter example
+
+```yaml
+---
+id: jwt-setup-dotnet9
+name: jwt-setup-dotnet9
+title: JWT Authentication ASP.NET 9
+summary: Production-ready JWT authentication setup for ASP.NET 9 APIs
+framework: aspnet
+version: .net9
+language: csharp
+category: auth
+tags:
+  - jwt
+  - authentication
+  - bearer
+difficulty: medium
+bestPractices:
+  - Use short-lived access tokens
+pitfalls:
+  - Do not hardcode signing keys
+securityNotes:
+  - Store secrets in a secure secret manager
+updatedAt: 2026-05-10
+---
+```
+
+## Non-Functional Targets
+
+- Snippet search target: under 500ms
+- MCP response target: under 1 second
+- Startup target: under 5 seconds
+
+## Roadmap Status
+
+- Phase 1 Foundation Hardening: Completed
+- Phase 2 PRD MVP Delivery: Completed
+- Phase 3 Relevance and Intelligence: Completed
+- Phase 4 Semantic Search and Platform Expansion: Not Started
+
+## Contributing
+
+Contributions are welcome through pull requests and issues.
+
+## License
+
+ISC
+
+## Author
+
+Mofaggol Hoshen
+
+## Links
+
+- Repository: https://github.com/MofaggolHoshen/dev-assist-mcp-server
+- Package: https://www.npmjs.com/package/@mofaggolhoshen/dev-assist-mcp
+- Product Requirements: docs/PRD-v2.md
+- Implementation Plan: docs/Implementation-Plan.md

package/content/concepts/circuit-breaker.md

@@ -0,0 +1,25 @@
+---
+id: circuit-breaker
+title: Circuit Breaker Pattern
+summary: Protect downstream systems by stopping repeated calls during failures.
+tags:
+  - resilience
+  - polly
+  - reliability
+---
+
+## Concept
+
+A circuit breaker monitors failures and opens when a threshold is crossed. While open, calls fail fast.
+After a delay, it enters half-open mode to test recovery.
+
+## When to Use
+
+- Unstable downstream API
+- Expensive external dependency
+- Cascading-failure protection
+
+## Anti-Patterns
+
+- Using retries without a breaker for persistent failures
+- Very long open durations that block recovery

package/content/setups/jwt-dotnet9.md

@@ -0,0 +1,18 @@
+---
+id: jwt-dotnet9
+title: JWT Setup for .NET 9
+summary: JWT setup guidance optimized for .NET 9 API projects.
+framework: dotnet9
+version: .net9
+tags:
+  - jwt
+  - auth
+  - dotnet9
+---
+
+## .NET 9 Notes
+
+- Use current authentication middleware defaults.
+- Keep token validation parameters explicit.
+- Integrate structured logging around auth failures.
+- Add health checks and startup validation for key configuration.

package/content/setups/jwt.md

@@ -0,0 +1,25 @@
+---
+id: jwt
+title: JWT Setup Baseline
+summary: Production-oriented JWT setup checklist for ASP.NET APIs.
+framework: aspnet
+version: .net8+
+tags:
+  - jwt
+  - auth
+  - security
+---
+
+## Setup Checklist
+
+1. Add JwtBearer package.
+2. Configure issuer, audience, and signing key validation.
+3. Enforce HTTPS and secure secret storage.
+4. Add authorization policies and role checks.
+5. Add token expiry and refresh-token strategy.
+
+## Validation
+
+- Reject tokens with invalid issuer or audience.
+- Reject expired tokens.
+- Rotate keys safely.

package/content/templates/clean-architecture.md

@@ -0,0 +1,25 @@
+---
+id: clean-architecture
+title: Clean Architecture Starter Template
+summary: Baseline folder and project layering for a Clean Architecture solution.
+framework: dotnet
+version: .net8+
+tags:
+  - clean-architecture
+  - ddd
+  - layering
+---
+
+## Suggested Structure
+
+- src/Application
+- src/Domain
+- src/Infrastructure
+- src/WebApi
+
+## Core Rules
+
+1. Domain has no dependency on infrastructure.
+2. Application contains use cases and contracts.
+3. Infrastructure implements contracts and adapters.
+4. Web API composes dependencies and hosts endpoints.

package/dist/content/snippetSchema.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/**
+ * Canonical schema for a DevAssist snippet file stored under snippets/.
+ *
+ * Required fields are the same as the original minimal shape.
+ * Optional fields represent Phase 1 metadata additions; all existing
+ * snippets that do not yet carry them will still parse successfully.
+ */
+export const snippetSchema = z.object({
+    /** Unique identifier — must match the filename without .json extension. */
+    name: z
+        .string()
+        .regex(/^[A-Za-z0-9-]+$/, "name must only contain letters, numbers, and hyphens"),
+    /** Human-friendly display title. */
+    title: z.string().min(1),
+    /** Primary programming language of the code example. */
+    language: z.string().min(1),
+    /** Short description of what the snippet does. */
+    description: z.string().min(1),
+    /** The source code or configuration example. */
+    code: z.string().min(1),
+    // ─── Phase 1 metadata additions ─────────────────────────────────────────
+    /** Top-level content category e.g. "auth", "resilience", "logging". */
+    category: z.string().optional(),
+    /** Searchable tags e.g. ["jwt", "bearer", "aspnet"]. */
+    tags: z.array(z.string()).optional(),
+    /** Target framework e.g. "aspnet", "dotnet", "nodejs". */
+    framework: z.string().optional(),
+    /** Target framework version e.g. ".net9", ".net8+", "node22". */
+    version: z.string().optional(),
+    /** Complexity level for the developer consuming the snippet. */
+    difficulty: z.enum(["beginner", "medium", "advanced"]).optional(),
+    /** Production-oriented best-practice notes. */
+    bestPractices: z.array(z.string()).optional(),
+    /** Common mistakes or anti-patterns to avoid. */
+    pitfalls: z.array(z.string()).optional(),
+    /** Security-specific guidance relevant to this snippet. */
+    securityNotes: z.array(z.string()).optional(),
+});

package/dist/index.js

@@ -5,6 +5,10 @@ import { listFilesTool } from "./tools/fs/listFiles.js";
 import { readFileTool } from "./tools/fs/readFile.js";
 import { searchCodeTool } from "./tools/fs/searchCode.js";
 import { getSnippetTool } from "./tools/knowledge/getSnippet.js";
+import { searchSnippetTool } from "./tools/knowledge/searchSnippet.js";
+import { getTemplateTool } from "./tools/knowledge/getTemplate.js";
+import { explainConceptTool } from "./tools/knowledge/explainConcept.js";
+import { generateSetupTool } from "./tools/knowledge/generateSetup.js";
 import { analyzeProjectTool } from "./tools/intelligence/analyzeProject.js";
 const server = new McpServer({ name: "dev-assist-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
 const registry = new ToolRegistry();
@@ -13,6 +17,10 @@ registry.register(listFilesTool);
 registry.register(readFileTool);
 registry.register(searchCodeTool);
 registry.register(getSnippetTool);
+registry.register(searchSnippetTool);
+registry.register(getTemplateTool);
+registry.register(explainConceptTool);
+registry.register(generateSetupTool);
 registry.register(analyzeProjectTool);
 for (const tool of registry.list()) {
     server.registerTool(tool.name, {

package/dist/schemas/markdownKnowledge.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export const markdownSnippetFrontmatterSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1).optional(),
+    title: z.string().min(1),
+    summary: z.string().min(1),
+    updatedAt: z
+        .union([
+        z.string(),
+        z.date().transform((date) => date.toISOString()),
+    ])
+        .optional(),
+    framework: z.string().optional(),
+    version: z.string().optional(),
+    language: z.string().optional(),
+    category: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    difficulty: z.enum(["beginner", "medium", "advanced"]).optional(),
+    bestPractices: z.array(z.string()).optional(),
+    pitfalls: z.array(z.string()).optional(),
+    securityNotes: z.array(z.string()).optional(),
+});
+export const markdownDocFrontmatterSchema = z.object({
+    id: z.string().min(1).optional(),
+    title: z.string().min(1),
+    summary: z.string().optional(),
+    framework: z.string().optional(),
+    version: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+});

package/dist/shared/response.js

@@ -0,0 +1,12 @@
+/**
+ * Shared MCP tool response helpers.
+ * All knowledge tools should use these helpers so output shape stays consistent.
+ */
+/** Wrap a plain string into a valid MCP tool content array. */
+export function textResponse(text) {
+    return { content: [{ type: "text", text }] };
+}
+/** Produce a structured error message in the same envelope. */
+export function errorResponse(message) {
+    return textResponse(`Error: ${message}`);
+}