Stats
Actions
Tags
From mcpserver
This skill should be used when the user asks to "ingest text into graphrag", "add document to knowledge graph", "create entity", "create relationship", "query knowledge graph", "list graph entities", "delete document"
How this skill is triggered — by the user, by Claude, or both
Slash command
/mcpserver:graphragThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
To interact with the workspace GraphRAG knowledge graph, use the `workflow.graphrag.*` REPL command namespace via `mcpserver-repl --agent-stdio`. Direct stdio input must be one single-line JSON request envelope per message, not formatted YAML. GraphRAG combines graph-based retrieval with semantic search, enabling richer context retrieval than vector-only approaches.
To interact with the workspace GraphRAG knowledge graph, use the workflow.graphrag.* REPL command namespace via mcpserver-repl --agent-stdio. Direct stdio input must be one single-line JSON request envelope per message, not formatted YAML. GraphRAG combines graph-based retrieval with semantic search, enabling richer context retrieval than vector-only approaches.
GraphRAG is disabled by default. Confirm it is active for the workspace before calling any operations — workflow.graphrag.status will report enabled: false if it has not been configured.
To inspect whether GraphRAG is enabled, initialized, and indexed for the active workspace:
type: request
payload:
requestId: req-20260409T120000Z-status-001
method: workflow.graphrag.status
params: {}
type: result
payload:
requestId: req-20260409T120000Z-status-001
result:
enabled: true
workspacePath: /workspace/my-project
graphRoot: /workspace/my-project/.graphrag
state: indexed
isInitialized: true
isIndexed: true
lastIndexedAtUtc: 2026-04-09T10:00:00Z
lastSuccessAtUtc: 2026-04-09T10:00:00Z
lastIndexDurationMs: 4200
lastIndexedDocumentCount: 38
inputDocumentCount: 38
backend: internal-fallback
Key state values: disabled, uninitialized, idle, indexing, indexed, error.
To rebuild the GraphRAG index from the current corpus:
type: request
payload:
requestId: req-20260409T120001Z-index-001
method: workflow.graphrag.index
params:
force: false
Set force: true to rebuild even when no corpus changes are detected. The response reports the post-index status including whether the job was started immediately or queued.
To run a natural-language query against the indexed graph:
type: request
payload:
requestId: req-20260409T120002Z-query-001
method: workflow.graphrag.query
params:
query: What authentication mechanisms does the system support?
mode: local
maxChunks: 10
includeContextChunks: true
maxEntities: 20
maxRelationships: 20
communityDepth: 2
responseTokenBudget: 2000
Valid mode values:
local — focuses on directly relevant entities and their immediate relationships; lower latencyglobal — traverses community structure for broad thematic answers; higher coveragedrift — follows conceptual drift to surface related but non-obvious connectionsAll params except query are optional. The result includes an answer, source citations, and optionally the raw chunks, entities, and relationships used:
type: result
payload:
requestId: req-20260409T120002Z-query-001
result:
query: What authentication mechanisms does the system support?
mode: local
answer: |
The system supports API key authentication via the X-Api-Key header,
workspace-scoped token rotation on server restart, and HMAC-SHA256
marker signature verification for agent bootstrap.
citations:
- sourceKey: docs/MCP-SERVER.md
chunkId: chunk-0042
snippet: "API key authentication is required for all /mcpserver/* endpoints..."
entities:
- ApiKeyAuthentication
- HmacSignatureVerification
relationships:
- ApiKeyAuthentication -> WorkspaceIsolation
fallbackUsed: false
backend: internal-fallback
To add a new document to the GraphRAG corpus without triggering a full reindex:
type: request
payload:
requestId: req-20260409T120003Z-ingest-001
method: workflow.graphrag.ingest
params:
content: |
JWT Authentication Design
The token service uses HS256 symmetric signing with a 256-bit workspace key.
Tokens expire after 1 hour. Refresh tokens use RS256 and expire after 30 days.
The JwtValidator class validates token signatures and extracts claims.
title: JWT Authentication Design
sourceType: adhoc-text
sourceKey: docs/jwt-auth-design
triggerReindex: false
Required: content. Optional fields:
title — human-readable document name (defaults to a generated ID if omitted)sourceType — classification tag, defaults to adhoc-textsourceKey — unique path/key for the document; defaults to title or a generated IDtriggerReindex — when true, starts a full index rebuild after ingestiontype: result
payload:
requestId: req-20260409T120003Z-ingest-001
result:
documentId: doc-a1b2c3d4
chunkCount: 4
tokenCount: 312
sourceType: adhoc-text
sourceKey: docs/jwt-auth-design
reindexTriggered: false
Store the returned documentId to manage the document later.
To browse documents in the corpus with pagination:
type: request
payload:
requestId: req-20260409T120004Z-doclist-001
method: workflow.graphrag.documents.list
params:
skip: 0
take: 50
sourceType: adhoc-text
The sourceType filter is optional. The result includes documents (array of summaries) and totalCount:
type: result
payload:
requestId: req-20260409T120004Z-doclist-001
result:
documents:
- id: doc-a1b2c3d4
sourceType: adhoc-text
sourceKey: docs/jwt-auth-design
ingestedAt: 2026-04-09T12:00:03Z
contentHash: sha256:abcdef1234...
chunkCount: 4
totalTokens: 312
totalCount: 1
To inspect the individual text chunks for a specific document:
type: request
payload:
requestId: req-20260409T120005Z-chunks-001
method: workflow.graphrag.documents.chunks
params:
documentId: doc-a1b2c3d4
type: result
payload:
requestId: req-20260409T120005Z-chunks-001
result:
documentId: doc-a1b2c3d4
chunks:
- id: chunk-0001
content: JWT Authentication Design. The token service uses HS256...
tokenCount: 78
chunkIndex: 0
- id: chunk-0002
content: Tokens expire after 1 hour. Refresh tokens use RS256...
tokenCount: 82
chunkIndex: 1
totalChunks: 4
To remove a document and all its chunks from the corpus:
type: request
payload:
requestId: req-20260409T120006Z-docdel-001
method: workflow.graphrag.documents.delete
params:
documentId: doc-a1b2c3d4
type: result
payload:
requestId: req-20260409T120006Z-docdel-001
result:
documentId: doc-a1b2c3d4
chunksRemoved: 4
success: true
Graph entities represent named concepts, people, organizations, or technical components extracted from or manually added to the corpus.
type: request
payload:
requestId: req-20260409T120007Z-entitycreate-001
method: workflow.graphrag.entities.create
params:
name: TokenService
entityType: component
description: Generates and signs JWT tokens using HS256 symmetric keys
metadata: '{"project":"McpServer","layer":"services"}'
Required: name, entityType. Optional: description, metadata (JSON string).
type: result
payload:
requestId: req-20260409T120007Z-entitycreate-001
result:
id: ent-001
name: TokenService
entityType: component
description: Generates and signs JWT tokens using HS256 symmetric keys
createdAtUtc: 2026-04-09T12:00:07Z
updatedAtUtc: 2026-04-09T12:00:07Z
type: request
payload:
requestId: req-20260409T120008Z-entitylist-001
method: workflow.graphrag.entities.list
params:
skip: 0
take: 50
entityType: component
The entityType filter is optional. Returns entities array and totalCount.
type: request
payload:
requestId: req-20260409T120009Z-entityget-001
method: workflow.graphrag.entities.get
params:
entityId: ent-001
type: request
payload:
requestId: req-20260409T120010Z-entityupdate-001
method: workflow.graphrag.entities.update
params:
entityId: ent-001
name: TokenService
entityType: component
description: Generates and signs JWT tokens; supports HS256 and RS256 algorithms
metadata: '{"project":"McpServer","layer":"services","updated":true}'
All fields in params replace the existing values; supply the full entity body, not a partial patch.
type: request
payload:
requestId: req-20260409T120011Z-entitydel-001
method: workflow.graphrag.entities.delete
params:
entityId: ent-001
Delete returns an empty result on success. Deleting an entity does not automatically remove its relationships; delete those separately first.
Relationships are directed edges between two entities with a typed label and optional weight.
type: request
payload:
requestId: req-20260409T120012Z-relcreate-001
method: workflow.graphrag.relationships.create
params:
sourceEntityId: ent-001
targetEntityId: ent-002
relationshipType: validates
description: TokenService uses JwtValidator to verify token signatures on refresh
weight: 0.9
metadata: '{"direction":"bidirectional"}'
Required: sourceEntityId, targetEntityId, relationshipType. Optional: description, weight (default 1.0), metadata.
type: result
payload:
requestId: req-20260409T120012Z-relcreate-001
result:
id: rel-001
sourceEntityId: ent-001
targetEntityId: ent-002
relationshipType: validates
description: TokenService uses JwtValidator to verify token signatures on refresh
weight: 0.9
createdAtUtc: 2026-04-09T12:00:12Z
updatedAtUtc: 2026-04-09T12:00:12Z
type: request
payload:
requestId: req-20260409T120013Z-rellist-001
method: workflow.graphrag.relationships.list
params:
skip: 0
take: 50
entityId: ent-001
type: validates
Both entityId and type filters are optional. entityId returns all relationships where the entity appears as source or target.
type: request
payload:
requestId: req-20260409T120014Z-relget-001
method: workflow.graphrag.relationships.get
params:
relationshipId: rel-001
type: request
payload:
requestId: req-20260409T120015Z-relupdate-001
method: workflow.graphrag.relationships.update
params:
relationshipId: rel-001
sourceEntityId: ent-001
targetEntityId: ent-002
relationshipType: validates
description: Updated description after code review
weight: 1.0
Supply the full relationship body; all fields replace existing values.
type: request
payload:
requestId: req-20260409T120016Z-reldel-001
method: workflow.graphrag.relationships.delete
params:
relationshipId: rel-001
Common error codes for GraphRAG operations:
graphrag_disabled — GraphRAG is not enabled for this workspacegraphrag_not_indexed — corpus exists but has not been indexed yet; call index firstdocument_not_found — no document with the specified IDentity_not_found — no entity with the specified IDrelationship_not_found — no relationship with the specified IDingestion_error — text could not be chunked or storedindex_error — indexing operation failed; check status for lastErrorTo add new knowledge and make it immediately queryable:
workflow.graphrag.status to verify GraphRAG is enabled: true and isIndexed: trueworkflow.graphrag.ingest with the raw text; set triggerReindex: false for batch ingestionworkflow.graphrag.entities.create to add curated entities from the textworkflow.graphrag.relationships.create to link new entities to existing onesworkflow.graphrag.index with force: false once all documents are ingestedworkflow.graphrag.query with mode: local to verify the new knowledge is retrievableFor large ingestion batches, ingest all documents first, then trigger a single index call at the end to minimize total indexing time.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub sharpninja/mcpserver-claude-code-plugin --plugin mcpserver