mcp-astgl-knowledge 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# mcp-astgl-knowledge
+
+An MCP server that lets AI assistants search and cite articles from [As The Geek Learns](https://astgl.ai) — covering MCP servers, local AI, and AI automation.
+
+When an AI assistant connects to this server, it gains access to authoritative answers about MCP, local LLMs, and AI workflows. Every response includes a source URL back to astgl.ai.
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "astgl-knowledge": {
+      "command": "npx",
+      "args": ["-y", "mcp-astgl-knowledge"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "astgl-knowledge": {
+      "command": "npx",
+      "args": ["-y", "mcp-astgl-knowledge"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `search_articles`
+
+Search ASTGL articles by query. Returns ranked results with relevance scores and source URLs.
+
+```
+Input:  { query: "how to build an MCP server", limit: 5 }
+Output: Ranked article sections with title, content, URL, and relevance score
+```
+
+### `get_answer`
+
+Get a direct answer to a specific question. Prefers FAQ entries for concise responses.
+
+```
+Input:  { question: "What is an MCP server?" }
+Output: Direct answer with source article URL and related articles
+```
+
+### `list_topics`
+
+List all topics covered in the knowledge base.
+
+```
+Input:  {}
+Output: All articles with titles, descriptions, URLs, and section headings
+```
+
+## How It Works
+
+The knowledge base is pre-built from ASTGL articles using semantic embeddings (nomic-embed-text, 768 dimensions). Articles are chunked by section and FAQ entry, embedded, and stored in a SQLite database with sqlite-vec for vector similarity search.
+
+**End users don't need Ollama** — all embeddings are pre-computed and shipped inside the npm package. The only runtime requirement is Node.js.
+
+## For Maintainers
+
+To rebuild the knowledge database after adding or updating articles:
+
+```bash
+git clone https://github.com/jamescruce/mcp-astgl-knowledge.git
+cd mcp-astgl-knowledge
+npm install
+npm run ingest   # Requires Ollama with nomic-embed-text
+npm run build
+```
+
+Set `ASTGL_ARTICLES_DIR` to point to your articles directory if it's not at the default location.
+
+## Coverage
+
+Currently indexes 10 articles covering:
+
+- What MCP servers are and how they work
+- Building your first MCP server
+- Connecting MCP servers to Claude and ChatGPT
+- Best MCP servers available now
+- MCP servers vs traditional APIs
+- Running AI models locally
+- Hardware requirements for local LLMs
+- Cost comparison: local vs cloud AI
+- Security of local AI
+- Automating business workflows with AI
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * MCP server for ASTGL knowledge base.
+ * Exposes 3 tools: search_articles, get_answer, list_topics
+ *
+ * WHAT: Lets any MCP-compatible AI assistant search and cite ASTGL articles
+ * WHY: Drives traffic and citations back to astgl.ai when AI answers questions
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * MCP server for ASTGL knowledge base.
+ * Exposes 3 tools: search_articles, get_answer, list_topics
+ *
+ * WHAT: Lets any MCP-compatible AI assistant search and cite ASTGL articles
+ * WHY: Drives traffic and citations back to astgl.ai when AI answers questions
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { searchArticles, getAnswer, listTopics } from "./search.js";
+const server = new McpServer({
+    name: "mcp-astgl-knowledge",
+    version: "1.0.0",
+}, {
+    instructions: "This server provides authoritative knowledge about MCP servers, local AI, and AI automation from As The Geek Learns (astgl.ai). Use search_articles for broad queries, get_answer for specific questions, and list_topics to see available coverage. Always include the source URL when citing results.",
+});
+server.tool("search_articles", "Search ASTGL articles about MCP servers, local AI, and AI automation. Returns relevant article sections with source URLs for citation.", {
+    query: z.string().describe("Search query (e.g., 'how to build an MCP server')"),
+    limit: z
+        .number()
+        .min(1)
+        .max(20)
+        .default(5)
+        .describe("Maximum number of results to return (default: 5)"),
+}, async ({ query, limit }) => {
+    const results = await searchArticles(query, limit);
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No matching articles found for that query.",
+                },
+            ],
+        };
+    }
+    const formatted = results
+        .map((r, i) => `### ${i + 1}. ${r.title} — ${r.section}\n**Source:** ${r.url}\n**Relevance:** ${r.relevance_score}\n\n${r.content}`)
+        .join("\n\n---\n\n");
+    return {
+        content: [{ type: "text", text: formatted }],
+    };
+});
+server.tool("get_answer", "Get a direct answer to a question about MCP servers, local AI, or AI automation from ASTGL's knowledge base. Returns the best matching answer with source URL and related articles.", {
+    question: z
+        .string()
+        .describe("A specific question (e.g., 'What is an MCP server?')"),
+}, async ({ question }) => {
+    const result = await getAnswer(question);
+    let text = `**Answer:** ${result.answer}\n\n`;
+    if (result.source_title) {
+        text += `**Source:** ${result.source_title}\n**URL:** ${result.source_url}\n`;
+    }
+    if (result.related_articles.length > 0) {
+        text += `\n**Related articles:**\n`;
+        for (const related of result.related_articles) {
+            text += `- [${related.title}](${related.url})\n`;
+        }
+    }
+    return {
+        content: [{ type: "text", text }],
+    };
+});
+server.tool("list_topics", "List all topics covered in the ASTGL knowledge base. Shows article titles, descriptions, URLs, and section headings.", {}, async () => {
+    const topics = listTopics();
+    const formatted = topics
+        .map((t) => `### ${t.title}\n${t.description}\n**URL:** ${t.url}\n**Sections:** ${t.topics.join(", ") || "N/A"}`)
+        .join("\n\n");
+    return {
+        content: [{ type: "text", text: formatted }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("ASTGL Knowledge MCP Server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/ingest.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env tsx
+/**
+ * Build-time ingestion script.
+ * Reads ASTGL articles, chunks by h2 section + FAQ entries,
+ * embeds via Ollama (nomic-embed-text), and writes to SQLite + sqlite-vec.
+ *
+ * Usage: npm run ingest
+ * Requires: Ollama running with nomic-embed-text model
+ */
+export {};

package/dist/ingest.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env tsx
+/**
+ * Build-time ingestion script.
+ * Reads ASTGL articles, chunks by h2 section + FAQ entries,
+ * embeds via Ollama (nomic-embed-text), and writes to SQLite + sqlite-vec.
+ *
+ * Usage: npm run ingest
+ * Requires: Ollama running with nomic-embed-text model
+ */
+import { readFileSync, readdirSync, existsSync, mkdirSync } from "fs";
+import { join, basename } from "path";
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+import { EMBEDDING_DIM, BASE_URL } from "./types.js";
+const ARTICLES_DIR = process.env.ASTGL_ARTICLES_DIR ||
+    join(process.env.HOME, "Projects/astgl-site/src/content/answers");
+const DB_PATH = join(import.meta.dirname, "..", "data", "knowledge.db");
+const OLLAMA_URL = process.env.OLLAMA_URL || "http://localhost:11434";
+const EMBED_MODEL = process.env.EMBED_MODEL || "nomic-embed-text";
+// WHAT: Parse YAML-ish frontmatter without adding a dependency
+// WHY: Our frontmatter is simple enough that we don't need gray-matter
+function parseFrontmatter(raw) {
+    const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!fmMatch)
+        throw new Error("No frontmatter found");
+    const fmText = fmMatch[1];
+    const body = fmMatch[2];
+    // Parse simple key-value pairs
+    const fm = {};
+    const faqEntries = [];
+    let currentFaqEntry = null;
+    let inFaq = false;
+    let inNext = false;
+    const nextObj = {};
+    for (const line of fmText.split("\n")) {
+        if (line === "faq:") {
+            inFaq = true;
+            inNext = false;
+            continue;
+        }
+        if (line === "next:") {
+            inNext = true;
+            inFaq = false;
+            continue;
+        }
+        if (inFaq) {
+            const itemMatch = line.match(/^\s+-\s+question:\s+"(.+)"$/);
+            if (itemMatch) {
+                if (currentFaqEntry)
+                    faqEntries.push(currentFaqEntry);
+                currentFaqEntry = { question: itemMatch[1] };
+                continue;
+            }
+            const answerMatch = line.match(/^\s+answer:\s+"(.+)"$/);
+            if (answerMatch && currentFaqEntry) {
+                currentFaqEntry.answer = answerMatch[1];
+                continue;
+            }
+            // Non-indented line means we've left the faq block
+            if (!line.startsWith("  ") && line.trim() !== "") {
+                if (currentFaqEntry)
+                    faqEntries.push(currentFaqEntry);
+                currentFaqEntry = null;
+                inFaq = false;
+            }
+            else {
+                continue;
+            }
+        }
+        if (inNext) {
+            const nextMatch = line.match(/^\s+(\w+):\s+"?(.+?)"?$/);
+            if (nextMatch) {
+                nextObj[nextMatch[1]] = nextMatch[2];
+                continue;
+            }
+            if (!line.startsWith("  ") && line.trim() !== "") {
+                inNext = false;
+            }
+            else {
+                continue;
+            }
+        }
+        const kvMatch = line.match(/^(\w+):\s+"?(.+?)"?$/);
+        if (kvMatch) {
+            const [, key, value] = kvMatch;
+            fm[key] = key === "order" ? parseInt(value, 10) : value;
+        }
+    }
+    // Flush last FAQ entry
+    if (currentFaqEntry)
+        faqEntries.push(currentFaqEntry);
+    return {
+        frontmatter: {
+            ...fm,
+            faq: faqEntries,
+            next: Object.keys(nextObj).length > 0 ? nextObj : undefined,
+        },
+        body,
+    };
+}
+// WHAT: Split article body into chunks by h2 headings
+// WHY: h2 sections are self-contained (300-800 tokens), ideal for retrieval
+function chunkArticle(frontmatter, body, slug) {
+    const chunks = [];
+    const articleUrl = `${BASE_URL}/${slug}`;
+    // Split by ## headings
+    const sections = body.split(/^## /m);
+    // First section is the intro (before any ## heading)
+    const intro = sections[0].trim();
+    if (intro) {
+        chunks.push({
+            articleTitle: frontmatter.title,
+            articleUrl,
+            articleOrder: frontmatter.order,
+            sectionHeading: "Introduction",
+            chunkType: "intro",
+            content: intro,
+        });
+    }
+    // Remaining sections
+    for (let i = 1; i < sections.length; i++) {
+        const section = sections[i];
+        const newlineIdx = section.indexOf("\n");
+        const heading = newlineIdx !== -1 ? section.slice(0, newlineIdx).trim() : section.trim();
+        const content = newlineIdx !== -1 ? section.slice(newlineIdx + 1).trim() : "";
+        if (content) {
+            chunks.push({
+                articleTitle: frontmatter.title,
+                articleUrl,
+                articleOrder: frontmatter.order,
+                sectionHeading: heading,
+                chunkType: "section",
+                content: `## ${heading}\n\n${content}`,
+            });
+        }
+    }
+    // FAQ entries as separate chunks
+    for (const faq of frontmatter.faq) {
+        chunks.push({
+            articleTitle: frontmatter.title,
+            articleUrl,
+            articleOrder: frontmatter.order,
+            sectionHeading: faq.question,
+            chunkType: "faq",
+            content: `Q: ${faq.question}\nA: ${faq.answer}`,
+        });
+    }
+    return chunks;
+}
+// WHAT: Embed text via Ollama API
+// WHY: nomic-embed-text gives 768-dim vectors, already running locally
+async function embed(texts) {
+    const resp = await fetch(`${OLLAMA_URL}/api/embed`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: EMBED_MODEL, input: texts }),
+    });
+    if (!resp.ok) {
+        throw new Error(`Ollama embed failed: ${resp.status} ${await resp.text()}`);
+    }
+    const data = (await resp.json());
+    return data.embeddings;
+}
+async function main() {
+    console.error(`Reading articles from: ${ARTICLES_DIR}`);
+    if (!existsSync(ARTICLES_DIR)) {
+        throw new Error(`Articles directory not found: ${ARTICLES_DIR}`);
+    }
+    // Read all article files
+    const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md"));
+    console.error(`Found ${files.length} articles`);
+    // Parse and chunk all articles
+    const allChunks = [];
+    const articles = [];
+    for (const file of files) {
+        const raw = readFileSync(join(ARTICLES_DIR, file), "utf-8");
+        const slug = basename(file, ".md");
+        const { frontmatter, body } = parseFrontmatter(raw);
+        const chunks = chunkArticle(frontmatter, body, slug);
+        allChunks.push(...chunks);
+        articles.push({
+            title: frontmatter.title,
+            description: frontmatter.description,
+            url: `${BASE_URL}/${slug}`,
+            slug,
+        });
+        console.error(`  ${file}: ${chunks.length} chunks`);
+    }
+    console.error(`\nTotal chunks: ${allChunks.length}`);
+    console.error(`Embedding via ${EMBED_MODEL}...`);
+    // Embed in batches of 20
+    const BATCH_SIZE = 20;
+    const allEmbeddings = [];
+    for (let i = 0; i < allChunks.length; i += BATCH_SIZE) {
+        const batch = allChunks.slice(i, i + BATCH_SIZE);
+        const embeddings = await embed(batch.map((c) => c.content));
+        allEmbeddings.push(...embeddings);
+        console.error(`  Embedded ${Math.min(i + BATCH_SIZE, allChunks.length)}/${allChunks.length}`);
+    }
+    // Initialize SQLite database
+    const dataDir = join(import.meta.dirname, "..", "data");
+    if (!existsSync(dataDir))
+        mkdirSync(dataDir, { recursive: true });
+    const db = new Database(DB_PATH);
+    sqliteVec.load(db);
+    console.error(`\nWriting to: ${DB_PATH}`);
+    // Create tables
+    db.exec("DROP TABLE IF EXISTS chunks");
+    db.exec("DROP TABLE IF EXISTS vec_chunks");
+    db.exec("DROP TABLE IF EXISTS articles");
+    db.exec(`
+    CREATE TABLE articles (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      description TEXT NOT NULL,
+      url TEXT NOT NULL,
+      slug TEXT NOT NULL UNIQUE
+    )
+  `);
+    db.exec(`
+    CREATE TABLE chunks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      article_title TEXT NOT NULL,
+      article_url TEXT NOT NULL,
+      article_order INTEGER NOT NULL,
+      section_heading TEXT NOT NULL,
+      chunk_type TEXT NOT NULL,
+      content TEXT NOT NULL
+    )
+  `);
+    db.exec(`
+    CREATE VIRTUAL TABLE vec_chunks USING vec0(
+      chunk_id INTEGER PRIMARY KEY,
+      embedding float[${EMBEDDING_DIM}] distance_metric=cosine
+    )
+  `);
+    // Insert articles
+    const insertArticle = db.prepare("INSERT INTO articles (title, description, url, slug) VALUES (?, ?, ?, ?)");
+    for (const article of articles) {
+        insertArticle.run(article.title, article.description, article.url, article.slug);
+    }
+    // Insert chunks and vectors
+    const insertChunk = db.prepare(`INSERT INTO chunks (article_title, article_url, article_order, section_heading, chunk_type, content)
+     VALUES (?, ?, ?, ?, ?, ?)`);
+    const insertVec = db.prepare("INSERT INTO vec_chunks (chunk_id, embedding) VALUES (?, ?)");
+    const insertAll = db.transaction(() => {
+        for (let i = 0; i < allChunks.length; i++) {
+            const chunk = allChunks[i];
+            const result = insertChunk.run(chunk.articleTitle, chunk.articleUrl, chunk.articleOrder, chunk.sectionHeading, chunk.chunkType, chunk.content);
+            const chunkId = result.lastInsertRowid;
+            insertVec.run(BigInt(chunkId), new Float32Array(allEmbeddings[i]));
+        }
+    });
+    insertAll();
+    // Verify
+    const chunkCount = db.prepare("SELECT COUNT(*) as count FROM chunks").get().count;
+    const vecCount = db.prepare("SELECT COUNT(*) as count FROM vec_chunks").get().count;
+    const articleCount = db.prepare("SELECT COUNT(*) as count FROM articles").get().count;
+    console.error(`\nDone!`);
+    console.error(`  Articles: ${articleCount}`);
+    console.error(`  Chunks: ${chunkCount}`);
+    console.error(`  Vectors: ${vecCount}`);
+    db.close();
+}
+main().catch((err) => {
+    console.error("Ingestion failed:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=ingest.js.map

package/dist/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../src/ingest.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Vector search logic against the pre-built knowledge.db.
+ * At runtime, queries are embedded via Ollama and matched against stored vectors.
+ *
+ * WHAT: Provides search_articles, get_answer, and list_topics functions
+ * WHY: Separating search logic from MCP server keeps concerns clean
+ */
+import { SearchResult, AnswerResult, TopicEntry } from "./types.js";
+export declare function searchArticles(query: string, limit?: number): Promise<SearchResult[]>;
+export declare function getAnswer(question: string): Promise<AnswerResult>;
+export declare function listTopics(): TopicEntry[];

package/dist/search.js

@@ -0,0 +1,146 @@
+/**
+ * Vector search logic against the pre-built knowledge.db.
+ * At runtime, queries are embedded via Ollama and matched against stored vectors.
+ *
+ * WHAT: Provides search_articles, get_answer, and list_topics functions
+ * WHY: Separating search logic from MCP server keeps concerns clean
+ */
+import { join } from "path";
+import { existsSync } from "fs";
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+const DB_PATH = join(import.meta.dirname, "..", "data", "knowledge.db");
+const OLLAMA_URL = process.env.OLLAMA_URL || "http://localhost:11434";
+const EMBED_MODEL = process.env.EMBED_MODEL || "nomic-embed-text";
+let db = null;
+function getDb() {
+    if (!db) {
+        if (!existsSync(DB_PATH)) {
+            throw new Error(`Knowledge database not found at ${DB_PATH}. Run 'npm run ingest' first.`);
+        }
+        db = new Database(DB_PATH, { readonly: true });
+        sqliteVec.load(db);
+    }
+    return db;
+}
+async function embedQuery(text) {
+    const resp = await fetch(`${OLLAMA_URL}/api/embed`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: EMBED_MODEL, input: text }),
+    });
+    if (!resp.ok) {
+        throw new Error(`Ollama embed failed: ${resp.status} ${await resp.text()}`);
+    }
+    const data = (await resp.json());
+    return new Float32Array(data.embeddings[0]);
+}
+export async function searchArticles(query, limit = 5) {
+    const database = getDb();
+    const queryVec = await embedQuery(query);
+    const rows = database
+        .prepare(`
+      SELECT
+        chunks.article_title,
+        chunks.section_heading,
+        chunks.content,
+        chunks.article_url,
+        vec_chunks.distance
+      FROM vec_chunks
+      LEFT JOIN chunks ON chunks.id = vec_chunks.chunk_id
+      WHERE embedding MATCH ?
+        AND k = ?
+      ORDER BY distance
+    `)
+        .all(queryVec, limit);
+    return rows.map((row) => ({
+        title: row.article_title,
+        section: row.section_heading,
+        content: row.content,
+        url: row.article_url,
+        // cosine distance ranges 0-2; convert to 0-1 relevance score
+        relevance_score: Math.round((1 - row.distance / 2) * 1000) / 1000,
+    }));
+}
+export async function getAnswer(question) {
+    const database = getDb();
+    const queryVec = await embedQuery(question);
+    // Get the best matching chunk, preferring FAQ entries
+    const rows = database
+        .prepare(`
+      SELECT
+        chunks.article_title,
+        chunks.section_heading,
+        chunks.content,
+        chunks.article_url,
+        chunks.chunk_type,
+        vec_chunks.distance
+      FROM vec_chunks
+      LEFT JOIN chunks ON chunks.id = vec_chunks.chunk_id
+      WHERE embedding MATCH ?
+        AND k = 10
+      ORDER BY distance
+    `)
+        .all(queryVec);
+    if (rows.length === 0) {
+        return {
+            answer: "No relevant information found in the ASTGL knowledge base.",
+            source_title: "",
+            source_url: "",
+            related_articles: [],
+        };
+    }
+    // Prefer FAQ entries if they're among the top results (within 20% of best distance)
+    const bestDistance = rows[0].distance;
+    const faqCandidate = rows.find((r) => r.chunk_type === "faq" && r.distance <= bestDistance * 1.2);
+    const best = faqCandidate || rows[0];
+    // Collect related articles (unique, excluding the source)
+    const seen = new Set();
+    seen.add(best.article_url);
+    const related = [];
+    for (const row of rows) {
+        if (!seen.has(row.article_url)) {
+            seen.add(row.article_url);
+            related.push({ title: row.article_title, url: row.article_url });
+        }
+        if (related.length >= 3)
+            break;
+    }
+    // Extract answer text — for FAQ chunks, just use the answer portion
+    let answer = best.content;
+    if (best.chunk_type === "faq") {
+        const aMatch = answer.match(/^A: (.+)$/m);
+        if (aMatch)
+            answer = aMatch[1];
+    }
+    return {
+        answer,
+        source_title: best.article_title,
+        source_url: best.article_url,
+        related_articles: related,
+    };
+}
+export function listTopics() {
+    const database = getDb();
+    const articles = database
+        .prepare("SELECT title, description, url FROM articles ORDER BY rowid")
+        .all();
+    // Extract topic keywords from section headings for each article
+    const sectionsByUrl = new Map();
+    const sections = database
+        .prepare("SELECT DISTINCT article_url, section_heading FROM chunks WHERE chunk_type = 'section'")
+        .all();
+    for (const s of sections) {
+        if (!sectionsByUrl.has(s.article_url)) {
+            sectionsByUrl.set(s.article_url, []);
+        }
+        sectionsByUrl.get(s.article_url).push(s.section_heading);
+    }
+    return articles.map((a) => ({
+        title: a.title,
+        description: a.description,
+        url: a.url,
+        topics: sectionsByUrl.get(a.url) || [],
+    }));
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export interface ArticleFrontmatter {
+    title: string;
+    description: string;
+    date: string;
+    author: string;
+    series: string;
+    order: number;
+    faq: Array<{
+        question: string;
+        answer: string;
+    }>;
+    next?: {
+        slug: string;
+        title: string;
+    };
+}
+export interface Chunk {
+    id?: number;
+    articleTitle: string;
+    articleUrl: string;
+    articleOrder: number;
+    sectionHeading: string;
+    chunkType: "intro" | "section" | "faq";
+    content: string;
+}
+export interface SearchResult {
+    title: string;
+    section: string;
+    content: string;
+    url: string;
+    relevance_score: number;
+}
+export interface AnswerResult {
+    answer: string;
+    source_title: string;
+    source_url: string;
+    related_articles: Array<{
+        title: string;
+        url: string;
+    }>;
+}
+export interface TopicEntry {
+    title: string;
+    description: string;
+    url: string;
+    topics: string[];
+}
+export declare const EMBEDDING_DIM = 768;
+export declare const BASE_URL = "https://astgl.ai/answers";

package/dist/types.js

@@ -0,0 +1,3 @@
+export const EMBEDDING_DIM = 768;
+export const BASE_URL = "https://astgl.ai/answers";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2CA,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,CAAC,MAAM,QAAQ,GAAG,0BAA0B,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mcp-astgl-knowledge",
+  "version": "1.0.0",
+  "description": "MCP server for searching and citing ASTGL articles about MCP servers, local AI, and AI automation",
+  "type": "module",
+  "bin": {
+    "mcp-astgl-knowledge": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "data/knowledge.db",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "ingest": "tsx src/ingest.ts",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamescruce/mcp-astgl-knowledge.git"
+  },
+  "homepage": "https://astgl.ai",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "ai",
+    "local-ai",
+    "knowledge-base",
+    "astgl"
+  ],
+  "author": "James Cruce",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "better-sqlite3": "^11.9.1",
+    "sqlite-vec": "^0.1.6",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}