convez.ai
MCP ServerSegurançaAvançado
kirinlin

KMIP Knowledge Base para Desenvolvedores

kirinlin/kmip-kb

KB estruturada de KMIP com RAG, busca BM25 e MCP servers

Ver no GitHub
InicialPluginScore · de 0 a 100

Base de conhecimento independente sobre o protocolo KMIP (Key Management Interoperability Protocol) da OASIS, estruturada para RAG, busca vetorial e agentes de código. Cobre especificações 1.x e 2.x com exemplos práticos, mapeamentos entre versões e metadados estruturados para integração com LLMs.

Instalação

$npx convez-ai kirinlin/kmip-kb

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
v0.29.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Implementar clientes/servidores KMIP conformes com especificações OASIS
  • Resolver dúvidas sobre operações, objetos, atributos e encoding TTLV
  • Mapear diferenças entre versões KMIP 1.0–2.1 e guiar migrações
  • Treinar agentes de IA e RAG sistemas sobre gerenciamento de chaves criptográficas

Veredito

Recurso técnico sólido e bem estruturado para quem trabalha com gerenciamento de chaves em conformidade OASIS. A cobertura multi-versão e os dois MCP servers (KB estruturado + spec raw) oferecem flexibilidade real para busca e integração com agentes, eliminando fricção em implementações KMIP complexas.

README

A tradução para o português deste README ainda está na fila.

kmip-dev

An independently written KMIP developer knowledge base — summaries, explanations, implementation guidance, examples, and machine-readable metadata for the OASIS Key Management Interoperability Protocol (KMIP), structured for LLM wikis, RAG / vector search, Graph RAG, and coding agents.

It targets the KMIP 1.x and 2.x specification families (v1.0–v1.4, v2.0–v2.1), with v2.1 as the baseline.

Structure

DirectoryContents
kb/concepts/Cross-cutting concepts: authentication, transport, error handling, key state.
kb/operations/Client-to-server operations; kb/operations/server-to-client/ for the reverse.
kb/objects/Managed objects (symmetric/asymmetric keys, certificates, secret data, templates).
kb/attributes/Object attributes — data types, constraints, applicability.
kb/encoding/TTLV wire encoding and bit masks.
kb/enumerations/KMIP enumerations (§11) — named value sets used in TTLV-encoded fields.
kb/structures/Data structures: object (Key Block, …), attribute, and operation building blocks.
kb/messages/Protocol message structures: request/response envelope and message fields.
kb/profiles/Conformance profiles and implementation conformance.
kb/usage-guide/Design goals, usage notes, usage examples, and deprecation guidance from the KMIP Usage Guide ([KMIP-UG]), sourced with ug- prefix on source_section.
kb/versions/Per-version TOC maps — 1.0-toc.yaml → 2.1-toc.yaml (104–234 sections), 1.0-prof-toc.yaml → 2.1-prof-toc.yaml (8–44 sections), and 1.0-ug-toc.yaml → 2.1-ug-toc.yaml (36–83 sections) — plus full 1.0–2.1 delta notes.
kb/references/Terminology and pointers to normative / non-normative references.
kb/workflows/End-to-end workflows that chain operations.
kb/examples/Worked request/response examples (original, not copied).
kb/mappings/Cross-version / cross-implementation mapping tables.
schemas/JSON Schemas and machine-readable contracts; schemas/agent/ holds Graph RAG relation files.
templates/Document skeletons used by the scaffold generator.
mcp_py/Two FastMCP servers: kmip-kb exposes the authored kb/ knowledge base; kmip-raw exposes raw crawled spec documents in raw/. Both offer BM25 search and document retrieval.

Each document carries YAML front matter validated against schemas/frontmatter.schema.json:

---
title: Create
category: operation
spec_version: "2.1"
spec_versions: ["1.0", "1.1", "1.2", "1.3", "1.4", "2.0", "2.1"]
source_section: "6.1.8"      # v2.1 baseline section — traceability only
v1_source_section: "4.1"     # v1.x section, when the concept existed there
status: draft                # stub | draft | reviewed
related: []
keywords: []
tag_hex: "420018"            # optional — 6-digit hex from §11.56 Tag Enumeration
xml_text: "CertificateRequest"     # optional — CamelCase XML text identifier (KMIP-ENCODE §6.1.3)
---

source_section is the v2.1 (baseline) section; v1_source_section records the v1.x section for the same concept (omitted for v2.x-only features). Docs for features removed in v2.0 carry source_section: "del_v2" with their last v1.x section in v1_source_section. status tracks progress: stub (generated skeleton) → draft (authored) → reviewed (human-verified per CONTRIBUTING.md).

Authoring status: 452 content documents — 452 reviewed, 0 draft, 0 stub. All categories are at 100% reviewed. Covers every KMIP 2.1 section: operations (client and server-to-client), attributes, objects, data structures (§3/§5/§7) and message structures (§8/§9), TTLV encoding (§10.1), all 64 enumerations (§11), bit masks (§12), algorithm implementation (§13), profiles (KMIP-Prof v1.0–v2.1), and 83 usage-guide articles (KMIP-UG v2.1). Validators clean (front-matter schema, no-verbatim, link resolution, field-table Tag/XML Element columns) per the CONTRIBUTING.md checklist. Remaining work is the planned content in kb/examples/, kb/workflows/, and kb/mappings/.

Tag field populator

scripts/populate_tag_fields.py adds tag_hex and xml_text frontmatter fields to any KB doc whose title matches a named KMIP tag. Parses all v1.x, v2.0, and v2.1 spec tag tables: v2.1 is the primary source (354 tags); earlier versions supply the 17 tags deprecated by v2.0 so that del_v2 docs are also covered. Implements the official KMIP-ENCODE §6.1.3 CamelCase algorithm verified against v2.1 test-case XML (e.g. X_509CertificateIdentifier, PKCS_12FriendlyName). Safe to re-run — skips docs that already have tag_hex.

python scripts/populate_tag_fields.py --dry-run   # preview matches
python scripts/populate_tag_fields.py              # apply

Field-table enrichment

scripts/enrich_field_tables.py adds Tag (6-digit hex) and XML Element (CamelCase name) columns to every Markdown table that documents a structure's or payload's fields — those whose header's first column is Field:

| Field | Tag | XML Element | Required | Description |
|---|---|---|---|---|
| Object Type | `420057` | `ObjectType` | Yes | The type of object being handed over. |

It draws on the same tag lookup as the front-matter populator, reuses an existing Tag column where one is present, fills only cells matching a named KMIP tag (non-tag fields stay blank), never overwrites populated cells, and is idempotent. --check exits non-zero if any table is stale (CI guard).

python scripts/enrich_field_tables.py --dry-run   # preview changes
python scripts/enrich_field_tables.py              # apply
python scripts/enrich_field_tables.py --check      # fail if any table is stale

Enumeration-table enrichment

scripts/enrich_enum_tables.py inserts or refreshes the Name | Value | XML Text | Description table in every enumeration doc under kb/enumerations/. Value is the 8-digit integer value (e.g. 00000001); XML Text is the CamelCase text per KMIP-ENCODE §6.1.3 that appears inside the XML element when encoding the value. --check exits non-zero if any table is stale (CI guard).

python scripts/enrich_enum_tables.py --dry-run   # preview changes
python scripts/enrich_enum_tables.py              # apply
python scripts/enrich_enum_tables.py --check      # fail if any table is stale

Scaffold generator

scripts/build_kb_scaffold.py parses a locally mirrored spec and (re)generates the directory structure, one empty stub per section, and the section→file map in kb/versions/<ver>-toc.yaml. It is pure standard library and never overwrites a file whose status is no longer stub, so it is safe to re-run as authoring proceeds.

python scripts/build_kb_scaffold.py            # generate for v2.1
python scripts/build_kb_scaffold.py --check    # validate all front matter
python scripts/build_kb_scaffold.py --toc-only # only refresh the TOC map
python scripts/build_kb_scaffold.py --prune    # delete orphaned stubs
FlagDefaultEffect
--version2.1KMIP version to scaffold from (1.0–1.4 and 2.0–2.1 all supported)
--sourcespecSource document: spec = KMIP-SPEC, prof = KMIP-Prof (writes <ver>-prof-toc.yaml, prefixes sections with prof-), ug = KMIP-UG (writes <ver>-ug-toc.yaml, prefixes sections with ug-)
--spec FILE(derived)Explicit raw spec path (overrides --version)
--out DIR.Output root
--toc-only(off)Only regenerate the TOC map
--no-stubs(off)Create dirs + TOC but no stub files
--check(off)Validate front matter against the JSON Schema and exit
--prune(off)Delete stub files no longer in the rules (keeps authored docs)

No-verbatim guard

scripts/check_verbatim.py enforces the no-verbatim rule mechanically: for every authored doc (status: draft or reviewed) it compares the prose against the doc's source_section in the raw spec and flags any shared run of 8+ words. Run it before committing authored content:

python scripts/check_verbatim.py kb/operations  # check a directory
python scripts/check_verbatim.py --n 8         # adjust the run length

MCP servers

Two FastMCP servers in mcp_py/ expose the project to coding agents over stdio. Both are pre-wired for Claude Code via .mcp.json.

ServerScriptIndexesTools
kmip-kbkmip_kb_server.pykb/ — 450+ authored articlessearch_kb, get_article, list_articles, get_related
kmip-rawkmip_raw_server.pyraw/ — 250+ crawled spec docssearch_raw, get_doc (paginated), list_docs

Start them manually with:

bash mcp_py/start_kmip-kb.sh   # activate venv and run kmip-kb via stdio
bash mcp_py/start_kmip-raw.sh  # activate venv and run kmip-raw via stdio

Note: kmip-raw requires a populated raw/kmip/ directory. If it is absent or empty the server exits immediately with a diagnostic message. Run python scripts/kmip_crawler.py first (see Source preparation below).

Dependencies (fastmcp, rank-bm25, pyyaml) are listed in mcp_py/requirements.txt. See mcp_py/README.md for quick-test commands and a full tool reference. A kmip-authoring skill at .claude/skills/kmip-authoring.md bundles authoring conventions and MCP tool guidance for agents working in this repo.

Contributing

See CONTRIBUTING.md for the content rules — most importantly the no-verbatim rule: never copy specification prose into tracked files.

Source preparation (private, local-only)

The knowledge base is written from a local mirror of the OASIS docs, which is not published here — raw/ is gitignored. To build that mirror, scripts/kmip_crawler.py crawls https://docs.oasis-open.org/kmip/ and converts pages to Markdown via PullMD (running locally, default http://localhost:3000, override with PULLMD_URL). Requires Python 3.11+ with requests and beautifulsoup4.

python scripts/kmip_crawler.py                          # crawl + download
python scripts/kmip_crawler.py --urls ./raw/kmip_urls.txt   # resume from saved URLs
FlagDefaultDescription
--out DIRrawOutput root directory
--workers N4Parallel download workers
--save-urls FILE./raw/kmip_urls.txtFile to write discovered URLs
--urls FILE—Skip crawl; use a previously saved URL list
--skip-file FILE./raw/404skip.txtSkip URLs listed in this file (e.g. known 404s); a missing file is ignored
--no-skip—Re-download files that already exist

Path prefixes listed in EXCLUDE_PREFIXES at the top of the script are pruned from both the crawl and any --urls list — currently the kmip-profiles/v3.0/csd01/test-cases/kmip-v3.0 subtree, which self-references into runaway depth from server mis-linking.

Progress and errors are logged to logs/kmip_crawler-{timestamp}.log.

Ver o original no GitHub

Bom para

Relacionados