Skip to main content
Glama
gkb-seo-mcp-server

gkb-seo-mcp-server

by nuppawat6

gkb-seo-mcp-server v7

Data-driven refactor ของ mcp-GKB-SEO — 20 tools (19 เดิม backward-compatible + gkb_coverage_report)

  • เริ่มอ่านที่: PR_DESCRIPTION.md (RCA 11 flaws + สถาปัตยกรรม + tool-by-tool)

  • ติดตั้ง/ย้ายระบบ: MIGRATION.md

  • แก้พฤติกรรม matcher: แก้ data/*.json — ไม่ต้องแตะโค้ด แล้วรัน gkb_coverage_report

npm install && npm run build && npm test   # 37/37
node dist/src/index.js                     # stdio MCP server

HTTP / URL mode

Build first, then start the Streamable HTTP MCP endpoint:

cd "D:\develop\mcp-GKB SEO\v7"
$env:GKB_SEO_ROOT="D:\develop\mcp-GKB SEO\v7"
npm run build
npm run start:http

URLs:

  • Health check: http://localhost:3000/health

  • MCP endpoint: http://localhost:3000/mcp

Use PORT to change the port:

$env:PORT="3001"
npm run start:http

MCP HTTP clients must send:

Accept: application/json, text/event-stream
Content-Type: application/json

Related MCP server: seo-gaca-mcp

Vercel

This project also includes Vercel serverless adapters:

  • GET /health -> api/health.js

  • POST /mcp -> api/mcp.js

Deploy from the project root:

cd "D:\develop\mcp-GKB SEO\v7"
npm run build
vercel

After deployment:

  • Health check: https://<your-project>.vercel.app/health

  • MCP endpoint: https://<your-project>.vercel.app/mcp

The Vercel deployment uses the bundled KB/, data/, and compiled dist/ folders declared in vercel.json.

Available Tools

20 tools
gkb_batch_content_generationBatch content orchestrationA
Read-onlyIdempotent

Orchestrate rules for MULTIPLE headings in one call (whole outline / whole homepage). Each item accepts the full v7 orchestrate params. include_relations:true adds shared-rule analysis across headings (which atomic sets repeat, which intents dominate) — useful for structure variety checks.

Inputs: items (required), include_relations.

gkb_batch_processBatch processB
Read-onlyIdempotent

Execute multiple operations in one call — types: query | smart_orchestrate | micro_query | validate | manifest. Response keeps the v6 envelope {summary,results,errors,timestamp}. smart_orchestrate ops accept v7 params (section_role, intent_override, unique_angle, max_intents).

Inputs: operations (required).

gkb_bulk_analysisBulk analysisC
Read-onlyIdempotent

Analyze multiple text targets: mode 'keyword_extraction' (top domain keywords per text), 'rule_mapping' (orchestrate per text = heading), or 'content_analysis' (length + KB keyword overlap). Kept from v6 for compatibility.

Inputs: mode (required), targets (required).

gkb_coverage_reportCoverage report (NEW v7)A
Read-onlyIdempotent

Introspection: intent→rules map, rule→intents map, orphan rules (unreachable via any intent), atomic-set integrity, and matcher trigger inventory. Run after ANY edit to data/*.json. v6 had no such tool — which is how 32 of 56 rules stayed unreachable unnoticed.

Inputs: no named parameters.

gkb_index(Re)build KB indexA
Idempotent

Extract metadata from knowledge .md files (GKB_KB_DIR) into gkb_index.jsonl (GKB_INDEX_PATH). v7: clean title extraction — skips markdown noise and AI-conversation openers, prefers the first real heading. The only tool that writes by default; degrades to in-memory with a warning if the index path is not writable.

Inputs: no named parameters.

gkb_manifestKnowledge map / system statusA
Read-onlyIdempotent

Summarise the index: totals by family, type, language. PURE READ — result returned in the response (v6 crashed with EPERM trying to write gkb_manifest.json into CWD). Pass persist:true to also snapshot into GKB_OUTPUT_DIR (best-effort, warns on failure).

Inputs: persist.

gkb_micro_queryMicro query (ultra-compact)A
Read-onlyIdempotent

Progressive disclosure: pipe-delimited rows id|family|type|title (~50-100 tokens). Follow with gkb_query or gkb_read_kb_content on the ids you need.

Inputs: id, tag, type, limit, +3 more.

gkb_preset_forbiddenForbidden Guard — restricted terms + lexical rules (LEX-002/003), payload inlinedA
Read-onlyIdempotent

Forbidden Guard — restricted terms + lexical rules (LEX-002/003), payload inlined. Returns records WITH inlined content (v7 payload contract).

Inputs: inline.

gkb_preset_ilgILG Quick Pick — internal-link rules + examples (PI 6.3.034/035), payload inlinedA
Read-onlyIdempotent

ILG Quick Pick — internal-link rules + examples (PI 6.3.034/035), payload inlined. Returns records WITH inlined content (v7 payload contract).

Inputs: inline.

gkb_preset_qualityQuality Control — validation + system statusA
Read-onlyIdempotent

Quality Control — validation + system status. Returns records WITH inlined content (v7 payload contract).

Inputs: inline.

gkb_preset_techTech QA — technical SEO signalsB
Read-onlyIdempotent

Tech QA — technical SEO signals. Returns records WITH inlined content (v7 payload contract).

Inputs: inline.

gkb_preset_topicalTopical Strategy — topical mapping guidelinesC
Read-onlyIdempotent

Topical Strategy — topical mapping guidelines. Returns records WITH inlined content (v7 payload contract).

Inputs: inline.

gkb_queryQuery KB metadataA
Read-onlyIdempotent

Filter metadata-only records by family/type/tag/keyword/pi_code/id (stateless, no full content).

Inputs: id, tag, type, limit, +3 more.

gkb_read_kb_contentRead KB contentB
Read-onlyIdempotent

Read full content from a KB file — v6 contract preserved: {filename, offset, limit} line-based → {content, total_lines, has_more}. v7: filename also accepts a record id (e.g. LEX-002); path resolves via GKB_SEO_ROOT/KB or GKB_KB_DIR (v6 hardcoded __dirname/KB and ignored the env root).

Inputs: filename (required), limit, offset.

gkb_relateRelate recordsA
Read-onlyIdempotent

Jaccard keyword similarity between one record and the rest of the index.

Inputs: id (required), limit.

gkb_rule_detailRule detailA
Read-onlyIdempotent

Full text of a single rule by code (R01..R56) + v7 machine metadata (intents, triggers, atomic set + full set members, expected output element). Full text is read from data/rules/rule_texts/.md when migrated; falls back to purpose_1line with a migration note.

Inputs: code (required).

gkb_rules_by_purposeRules by purposeA
Read-onlyIdempotent

Filter the 56-rule table by purpose bucket: structure | lexical | EEAT | unique | all. Specific buckets exclude off-topic rules (R31/R32).

Inputs: purpose (required).

gkb_rules_indexRules indexA
Read-onlyIdempotent

Compact table of all 56 rules: code + title + 1-line purpose + category + always_on + NEW v7 fields (intents, atomic_set, output_element). Use first to see what exists.

Inputs: no named parameters.

gkb_smart_orchestrateSmart orchestrate (v7)A
Read-onlyIdempotent

Suggest rules for a heading (retriever+suggester, NOT a decider). v7 contract: matched:false means ZERO candidates + disambiguation_questions (no silent generic set). Atomic sets are served COMPLETE (TABLE_SET incl. R14 outro; STEP/LIST incl. R10 outro). why_matched names the exact trigger tokens. For Sales/homepage sections ALWAYS pass section_role — sales headings are benefit statements with no intent keywords and cannot be classified from text alone. expected_document_shape feeds the writing skill's G42 structure-parity gate.

Inputs: heading (required), max_intents, section_role, unique_angle, +1 more.

gkb_validateValidate KB filesA
Read-onlyIdempotent

Check all indexed files exist and SHA256 hashes match. PURE READ — returns {ok, missing, hash_mismatches} in the response (v6 crashed writing runlog.json to CWD). persist:true snapshots to GKB_OUTPUT_DIR, best-effort.

Inputs: persist.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: batch generation, batch processing, bulk analysis, coverage reporting, indexing, manifest summary, micro query, multiple presets for different aspects, query, read content, similarity, rule detail, rule filtering, rule index, smart orchestration, and validation. No significant overlap.

    Naming Consistency5/5

    All tools follow the `gkb_` prefix with consistent snake_case naming. Most use a verb_noun pattern (e.g., `batch_process`, `read_kb_content`, `smart_orchestrate`). Minor compound names like `rules_by_purpose` are still consistent with the overall style.

    Tool Count4/5

    20 tools is slightly high but justified by the complexity of the SEO knowledge base domain. Each tool covers a specific function, and there is no redundancy. A few tools could potentially be merged (e.g., the preset tools), but the count is still reasonable.

    Completeness4/5

    The tool surface covers core operations: content generation, batch processing, analysis, introspection, indexing, query, validation, and rule management. Minor gaps exist (e.g., no explicit update or delete tools for KB items), but the server's primary purpose is reading/analyzing the KB, and the descriptions imply external editing of data files.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for on-page SEO auditing and JSON-LD schema validation, providing tools for full SEO audit, schema validation, heading hierarchy, and image audit without requiring API keys.
      4
      68 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server for SEO, performance, GEO, and UX audits with 37 tools covering technical SEO, Lighthouse performance, AI search optimization, content analysis, accessibility, security, and more.
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that gives AI assistants 23 SEO tools for rank tracking, Google Analytics, site audits, keyword research, competitive analysis, and more, accessible through natural language.
      25
      12
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides comprehensive SEO analysis tools with actionable fix instructions for AI assistants like Claude Code and Claude Desktop.
      MIT