Context Engineering

Assess, enrich, compose, and deliver MCP servers from existing APIs using the Naftiko v0.5 capability framework. This project breaks context engineering into seven capability areas — Profile, Enrich, Compose, Generate, Publish, Discover, and Observe — each exposed as HTTP, MCP, and Agent Skill adapters.

See ROADMAP.md for planned capability expansions across Govern, Cost Attribution, and Developer Experience.

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          PROFILE (5)                                │
│  AI Readiness  Context Efficiency  MCP Inventory  MCP Duplicates   │
│  API Doc Quality                                                   │
└────────────────────────────────┬────────────────────────────────────┘
                                 ▼
                    Assessed API & MCP Landscape
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│   ENRICH (4)     │ │   COMPOSE (4)    │ │                  │
│ AI Descriptions  │ │ MCP Tools        │ │  Reuse across:   │
│ Examples         │ │ Server Bounds    │ │  • HTTP endpoints│
│ Task Mapping     │ │ Context Schemas  │ │  • MCP tools     │
│ Context Annot.   │ │ Context Overlays │ │  • Agent Skills  │
└────────┬─────────┘ └────────┬─────────┘ └──────────────────┘
         └────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│  GENERATE (3)    │ │   PUBLISH (4)    │ │  DISCOVER (3)    │
│ MCP from OpenAPI │ │ Backstage        │ │ MCP Servers      │
│ MCP from Arazzo  │ │ GitHub Registry  │ │ Semantic Search  │
│ MCP Sandbox      │ │ Docker           │ │ Recommendations  │
│                  │ │ Microcks         │ │                  │
└──────────────────┘ └──────────────────┘ └──────────────────┘
                              │
                    ┌─────────┘
                    ▼
         ┌──────────────────┐
         │   OBSERVE (4)    │
         │ Usage Datadog    │
         │ Usage New Relic  │
         │ Context Cost     │
         │ Context Quality  │
         └──────────────────┘

---

Capabilities

Profile (5 capabilities) — Assess AI-Readiness

Capability	Source	What It Does
profile-openapi-ai-readiness	OpenAPI Specs	Score specs on AI-readiness: description quality, example coverage, schema completeness, parameter disambiguation
profile-openapi-context-efficiency	OpenAPI Specs	Analyze token cost of API responses, identify bloated payloads, flag fields that waste context window
profile-mcp-inventory	Backstage / GitHub	Inventory existing MCP servers across the org — who built what, where, with what auth
profile-mcp-duplicates	MCP Registry	Detect duplicate or overlapping MCP tools across teams
profile-api-doc-quality	OpenAPI Specs	Assess documentation quality for AI consumption — description completeness, example presence, disambiguation

Enrich (4 capabilities) — Make APIs AI-Ready

Capability	Source	What It Does
enrich-openapi-ai-descriptions	OpenAPI Specs	Rewrite operation summaries and descriptions for AI-first consumption — explicit context, disambiguated parameters, task-oriented framing
enrich-openapi-examples	OpenAPI Specs	Generate request/response examples for each operation — critical for agent context and few-shot prompting
enrich-openapi-task-mapping	OpenAPI Specs	Map API paths to business tasks — "send a notification" not "POST /v2/notifications/{id}/dispatch"
enrich-openapi-context-annotations	OpenAPI Specs	Add x-context annotations: when to call, what it returns, prerequisites, side effects

Compose (4 capabilities) — Right-Size Context

Capability	Source	What It Does
compose-mcp-tools	Enriched OpenAPI	Group API operations into domain-aligned MCP tools — business-task-oriented, not 1:1 endpoint mapping
compose-mcp-server-boundaries	Capability Inventory	Define server boundaries by domain and use-case — one MCP server per Scrum team or business domain
compose-context-schemas	OpenAPI Schemas	Define typed output schemas that right-size responses — strip unnecessary fields, shape payloads for agents
compose-context-overlays	OpenAPI Overlays	Apply OpenAPI Overlays to customize specs for AI contexts without modifying originals

Generate (3 capabilities) — Produce MCP Servers

Capability	Source	What It Does
generate-mcp-from-openapi	Enriched OpenAPI	Generate Naftiko MCP server capability YAML from enriched OpenAPI specs — the core OpenAPI-to-MCP path
generate-mcp-from-arazzo	Arazzo Workflows	Generate MCP servers from Arazzo workflow definitions — multi-step API orchestrations as single MCP tools
generate-mcp-sandbox	OpenAPI + Examples	Generate MCP sandbox and mock servers for testing and evaluation before production deployment

Publish (4 capabilities) — Deploy & Register

Capability	Source	What It Does
publish-mcp-backstage	Naftiko Capabilities	Register MCP servers in Backstage catalog alongside existing API entities
publish-mcp-github-registry	Naftiko Capabilities	Register in GitHub's MCP server registry per organization
publish-mcp-docker	Naftiko Capabilities	Package MCP servers as Docker containers via Naftiko framework
publish-mcp-microcks	OpenAPI + Examples	Publish to Microcks for MCP server mocking and sandbox testing

Discover (3 capabilities) — Find Available Context

Capability	Source	What It Does
discover-mcp-servers	Backstage / GitHub	Discover available MCP servers across the org — unified view of what's available
discover-mcp-semantic	MCP Registry	Intent-based search across MCP tools — describe what you need, get ranked matches
discover-context-recommendations	Usage Data	Recommend relevant MCP tools and context sources for a given task or domain

Observe (4 capabilities) — Monitor & Optimize

Capability	Source	What It Does
observe-mcp-usage-datadog	Datadog	Track MCP tool call volumes, patterns, errors, latency in existing observability
observe-mcp-usage-newrelic	New Relic	MCP usage metrics as custom events and deployment markers in New Relic
observe-context-cost	Usage + Billing	Attribute token and upstream API costs to capabilities — AI FinOps at the capability level
observe-context-quality	Agent Logs	Evaluate agent-API interaction quality — hallucination rates, tool selection accuracy, context efficiency

---

Shared Adapters

New adapters created for this project (complement the 31 adapters in the capabilities repo and 7 in api-reusability):

Adapter	Service
consumes-microcks.yml	Microcks API — mock import, test runs, conformance
consumes-docker.yml	Docker Engine API — image builds, container lifecycle

Existing adapters consumed from other repos:

• consumes-github.yml — GitHub REST API v3 (Profile, Publish)
• consumes-backstage.yml — Backstage Software Catalog API (Profile, Publish, Discover)
• consumes-datadog.yml — Datadog API v1/v2 (Observe)
• consumes-newrelic.yml — New Relic REST API v2 (Observe)

---

Exposure Modes

Every capability is exposed three ways, aligned with the Naftiko framework:

Mode	Description
HTTP	REST endpoint (e.g. POST /profile/ai-readiness) for direct integration
MCP	Model Context Protocol tool under the context-engineering namespace
Agent Skill	Agent skill adapter for agentic orchestration workflows

---

Design Partner Sources

Partner	Key Contributions
Ford (John Musser)	MCP registry, streaming/SSE, auth flows (OBO), FinOps, governance layers
Cvent (Jeff Seifert)	Domain-driven MCP servers, 100+ Scrum teams, OpenAPI + Arazzo + overlays, Backstage
Avalara (Joshua McMillen)	Rewriting docs for AI, business-aligned tools, AI-automated onboarding
Chase	Semantic search for API marketplace, metadata quality for AI, Spectral rules
Microsoft (Sébastien Levert)	Skills as orchestrators of MCP tools, Work IQ as context, developer evangelism
Speakeasy (Patrick Kelly)	SDK/MCP generation, API evaluation for agents, sandbox/testing