mcp-astgl-knowledge

An MCP server that lets AI assistants search and cite content from As The Geek Learns — covering MCP servers, local AI, AI automation, and ASTGL project documentation.

When an AI assistant connects to this server, it can search the indexed ASTGL entries (articles, tutorials, comparisons, guides, and project docs). Search results include source URLs back to astgl.ai.

Requirement: the semantic tools (search_articles, get_answer, get_tutorial, compare_topics) embed your query at runtime with a local Ollama running nomic-embed-text (default http://localhost:11434). The metadata tools (find_articles, list_tags, list_topics, get_latest) work without Ollama.

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"]
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"]
    }
  }
}

Cursor / Generic MCP Client

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"]
    }
  }
}

With Registration (500 queries/day)

Register via the register tool to get an API key, then add it to your config:

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"],
      "env": {
        "ASTGL_API_KEY": "astgl_your_api_key_here"
      }
    }
  }
}

Tools

search_articles

Search the knowledge base by query. Returns ranked results with relevance scores and source URLs.

get_answer

Get a direct answer to a specific question. Prefers FAQ entries for concise responses.

get_tutorial

Get step-by-step instructions from tutorial and guide content.

compare_topics

Side-by-side comparison of two topics.

get_latest

Get the most recently added content.

list_topics

Browse all topics in the knowledge base with content types and section headings.

register

Register your email to unlock 500 queries/day (up from 50).

More tools

The server registers 17 tools in total. The others:

Content Types

Counts change as content is added; call list_topics or list_tags for the current index. draft and synthesis entries exist only in the maintainer database and are removed from the published one. The content_type descriptions in the tool schemas list only the first seven types.

Rate Limits

Limits reset at midnight UTC. Rate limit info is included in every response.

Limits and registrations are enforced by the server process itself: usage and registrations are kept in a local SQLite file (data/query-log.db next to the package, or ASTGL_QUERY_LOG_DB), and anonymous clients get a persistent ID in ~/.astgl-client-id. An ASTGL_API_KEY only counts as registered if it exists in that local registrations table.

How It Works

The knowledge base is pre-built from ASTGL articles using semantic embeddings (nomic-embed-text, 768 dimensions). Content is chunked by section and FAQ entry, embedded, and stored in a SQLite database with sqlite-vec for vector similarity search.

Article embeddings are pre-computed and shipped in the npm package, so you never re-index content. Your query is still embedded at runtime through Ollama for the semantic tools (see the requirement above).

The server opens data/knowledge.db when it exists (a maintainer checkout) and otherwise build/knowledge-public.db. The npm package ships only build/knowledge-public.db, which npm run build-public-db produces by physically removing every non-public row (see docs/adr/).

Performance

• Typical response time: 100-500ms (embedding lookup + vector search)
• Embedding results are cached in memory (LRU, 200 entries) — repeated queries are near-instant
• Ollama calls include 10s timeout + automatic retry
• Query logging is async/batched to avoid blocking responses
• Rate limit checks are cached for 5 seconds

For Maintainers

Setup

git clone https://github.com/Jmeg8r/mcp-astgl-knowledge.git
cd mcp-astgl-knowledge
npm install

Scripts

Other maintainer scripts (draft ingest and reconcile, rewrite queue, wiki sync, backup pruning, dashboard data, MCPB bundle) are listed in package.json.

Environment Variables

Automated Jobs

Schedules are defined in cron/*.json; the scheduled report jobs print JSON that an external scheduler picks up and delivers. Run the report scripts with --discord to post to DISCORD_WEBHOOK_URL instead. macOS launchd plists for the pipeline, draft and wiki jobs are in launchd/.

Architecture

flowchart TD
    Client["MCP client<br/>(Claude, Cursor, ...)"] -->|"stdio"| Server["MCP server<br/>src/index.ts (17 tools)"]
    Server --> RL["Rate limit + query log<br/>data/query-log.db"]
    Server --> Search["src/search.ts"]
    Search -->|"embed query"| Ollama["Ollama<br/>nomic-embed-text"]
    Search -->|"sqlite-vec KNN"| KDB[("knowledge.db<br/>or knowledge-public.db")]
    Sources["astgl.ai RSS / sitemap<br/>+ local markdown"] -->|"discover, structure, ingest"| KDB
    KDB -->|"build-public-db"| Pub[("build/knowledge-public.db<br/>(shipped in npm)")]
    Jobs["Report jobs<br/>daily report, alerts, freshness"] -.->|"--discord (manual)"| Discord["Discord webhook"]

A rendered diagram is in docs/diagrams/mcp-astgl-knowledge.architecture.svg (source: docs/diagrams/mcp-astgl-knowledge.architecture.json).

License

MIT