Merge pull request #144 from QuantGeekDev/feat/mcp-framework-docs

feat: add @mcp-framework/docs package

Author: QuantGeekDev

.gitignore

@@ -15,3 +15,4 @@ coverage/
 *~
 .yalc
 yalc.lock
+plans/

docs/docs-package/caching.md

@@ -0,0 +1,128 @@
+# Caching
+
+`@mcp-framework/docs` includes a built-in caching layer that reduces HTTP requests to your documentation site. All source adapters use caching automatically.
+
+## Default Cache
+
+The default `MemoryCache` is an in-memory LRU (Least Recently Used) cache with TTL (Time-To-Live) expiry.
+
+### What Gets Cached
+
+| Content | Cache Key | Default TTL |
+|---------|-----------|-------------|
+| `llms.txt` content | `index:{baseUrl}` | `refreshInterval` |
+| `llms-full.txt` content | `full:{baseUrl}` | `refreshInterval` |
+| Individual page content | `page:{slug}` | `refreshInterval` |
+| Search results | `search:{query}:{section}:{limit}` | `refreshInterval` |
+| Parsed section tree | `sections:{baseUrl}` | `refreshInterval` |
+
+### Configuration
+
+```typescript
+import { MemoryCache, LlmsTxtSource } from "@mcp-framework/docs";
+
+const cache = new MemoryCache({
+  maxEntries: 200,       // Default: 100
+  ttlMs: 600_000,        // Default: 300_000 (5 minutes)
+});
+
+const source = new LlmsTxtSource({
+  baseUrl: "https://docs.example.com",
+  cache,
+});
+```
+
+The `refreshInterval` option on source adapters sets the TTL for the default cache. If you provide a custom cache, the `ttlMs` on the cache takes precedence.
+
+## Cache Behavior
+
+- **Lazy expiry** — Expired entries are cleaned on access, not via a background timer. This avoids interval leaks.
+- **LRU eviction** — When `maxEntries` is reached, the oldest entry is evicted to make room for new ones.
+- **Per-entry TTL** — Each `set()` call can override the default TTL.
+- **Overwrite resets TTL** — Storing the same key again resets the expiry timer.
+
+## Cache Interface
+
+Implement this interface for custom backends (Redis, SQLite, etc.):
+
+```typescript
+interface Cache {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  stats(): { hits: number; misses: number; size: number };
+}
+```
+
+### Example: Redis Cache
+
+```typescript
+import { Cache, CacheStats } from "@mcp-framework/docs";
+import { createClient } from "redis";
+
+class RedisCache implements Cache {
+  private client;
+  private defaultTtl: number;
+  private _hits = 0;
+  private _misses = 0;
+
+  constructor(redisUrl: string, ttlMs = 300_000) {
+    this.client = createClient({ url: redisUrl });
+    this.defaultTtl = ttlMs;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const value = await this.client.get(`docs:${key}`);
+    if (!value) {
+      this._misses++;
+      return null;
+    }
+    this._hits++;
+    return JSON.parse(value);
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    const ttl = Math.ceil((ttlMs ?? this.defaultTtl) / 1000);
+    await this.client.set(`docs:${key}`, JSON.stringify(value), { EX: ttl });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.del(`docs:${key}`);
+  }
+
+  async clear(): Promise<void> {
+    // Careful: only clear docs: keys
+    const keys = await this.client.keys("docs:*");
+    if (keys.length > 0) await this.client.del(keys);
+    this._hits = 0;
+    this._misses = 0;
+  }
+
+  stats(): CacheStats {
+    return { hits: this._hits, misses: this._misses, size: -1 };
+  }
+}
+```
+
+## Cache Invalidation
+
+In v1, cache invalidation is **TTL-based only**. When the TTL expires, the next request triggers a fresh fetch. There is no webhook-based or push-based invalidation.
+
+For near-real-time updates, set a shorter `refreshInterval`:
+
+```typescript
+const source = new FumadocsRemoteSource({
+  baseUrl: "https://docs.example.com",
+  refreshInterval: 60_000, // Re-fetch every minute
+});
+```
+
+For less frequently changing docs, increase it:
+
+```typescript
+const source = new FumadocsRemoteSource({
+  baseUrl: "https://docs.example.com",
+  refreshInterval: 3_600_000, // Re-fetch every hour
+});
+```

docs/docs-package/cli.md

@@ -0,0 +1,121 @@
+# CLI & Project Scaffolding
+
+`@mcp-framework/docs` includes a CLI tool that scaffolds a ready-to-run documentation MCP server project.
+
+## Creating a Project
+
+```bash
+npx create-docs-server my-api-docs
+```
+
+This creates a project with the following structure:
+
+```
+my-api-docs/
+├── src/
+│   └── index.ts          # Pre-configured DocsServer with FumadocsRemoteSource
+├── package.json          # Dependencies on mcp-framework + @mcp-framework/docs
+├── tsconfig.json         # TypeScript configuration
+├── .env.example          # DOCS_BASE_URL, optional DOCS_API_KEY
+├── .gitignore
+└── README.md             # Setup instructions and MCP client config
+```
+
+## Generated Files
+
+### `src/index.ts`
+
+```typescript
+import { DocsServer, FumadocsRemoteSource } from "@mcp-framework/docs";
+
+const source = new FumadocsRemoteSource({
+  baseUrl: process.env.DOCS_BASE_URL || "https://docs.example.com",
+  headers: process.env.DOCS_API_KEY
+    ? { Authorization: `Bearer ${process.env.DOCS_API_KEY}` }
+    : undefined,
+});
+
+const server = new DocsServer({
+  source,
+  name: process.env.DOCS_SERVER_NAME || "my-api-docs",
+  version: "1.0.0",
+});
+
+server.start();
+```
+
+### `.env.example`
+
+```bash
+DOCS_BASE_URL=https://docs.example.com
+DOCS_SERVER_NAME=my-api-docs
+# DOCS_API_KEY=your-api-key-here
+```
+
+## Setup After Scaffolding
+
+```bash
+cd my-api-docs
+cp .env.example .env
+# Edit .env with your documentation site URL
+npm run build
+npm start
+```
+
+## Connecting to MCP Clients
+
+### Claude Code
+
+```bash
+claude mcp add my-api-docs -- node /path/to/my-api-docs/dist/index.js
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-api-docs": {
+      "command": "node",
+      "args": ["/path/to/my-api-docs/dist/index.js"],
+      "env": {
+        "DOCS_BASE_URL": "https://docs.myapi.com"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to MCP settings:
+
+```json
+{
+  "my-api-docs": {
+    "command": "node",
+    "args": ["/path/to/my-api-docs/dist/index.js"],
+    "env": {
+      "DOCS_BASE_URL": "https://docs.myapi.com"
+    }
+  }
+}
+```
+
+## SKILL.md Template
+
+The package includes a `SKILL.md.template` that you can customize to teach Claude Code how to approach integrations against your API. Copy it into your project:
+
+```bash
+cp node_modules/@mcp-framework/docs/SKILL.md.template SKILL.md
+# Edit SKILL.md with your API-specific patterns
+```
+
+The template includes `<!-- CUSTOMIZE -->` markers for sections you should edit:
+- Authentication patterns
+- SDK initialization
+- Common API call patterns
+- Error handling
+- Common pitfalls