[CEP-15] Common Tool Schemas

[ContextVM-org]

Preamble

• Title: Common Tool Schemas
• Authors: ContextVM-org
• Status: Draft

Abstract

This CEP establishes a standard for defining and discovering common tool schemas in ContextVM, enabling interoperability by allowing multiple servers to implement standardized tool interfaces. Using MCP's _meta field, RFC 8785 for deterministic hashing, and CEP-6 announcements for discovery, this creates a marketplace where users can choose between multiple providers implementing the same standard tool interface.

Motivation

Enables a marketplace for common services in ContextVM. When servers implement similar functionality (translation, weather, search), clients currently cannot discover equivalent services, switch providers without code changes, or build specialized UIs for standard tool types. Common tool schemas enable provider competition, user choice, and seamless interoperability.

Specification

The proposal introduces a reference server pattern where servers define canonical tool schemas identified by (serverPubkey, toolName). Implementing servers can then conform to these schemas. Schema verification uses RFC 8785 JCS for deterministic hashing. Discovery leverages CEP-6 announcements with D (defines) and I (implements) tags. The full specification is available in the accompanying PR.

Rationale

This design aligns with MCP's architecture by using the existing _meta field for extensibility and server-based versioning. It avoids creating new event kinds by leveraging CEP-6 announcements. The server-anchored approach ensures canonical authority while enabling decentralized discovery. The hash includes tool names to guarantee interoperability across implementations.

Backwards Compatibility

Fully backward compatible: existing clients ignore _meta fields and use tools normally, existing servers work without modifications, and CEP-6 tags are additive. The _meta field is part of the MCP specification, ensuring no breaking changes.

Readable spec

Resolves: #14

[abhayguptas]

Hello ContextVM team,

I have been reading through this proposal and the related specification material, and I wanted to say that this is one of the most interesting BSoC ideas in the list. The focus on shared tool schemas feels very important for ContextVM because it can make provider discovery, compatibility, and switching much more practical for real clients.

As I went through the details, two things stood out to me. One is that the proposal now seems centered on schema-based compatibility, which looks like a strong foundation for interoperability across different providers. The other is that schema hashing will likely need especially clear rules around what is and is not part of compatibility, so that tools which are functionally the same do not accidentally diverge because of descriptive schema fields.

I would be very interested in contributing to this work, especially around refining the proposal, validating discovery and conformance flows, and helping produce examples or tests that make the standard easier to implement in practice.

[ContextVM-org]

Thanks for your interest in this CEP. We also believe it is an important step toward decentralized discovery of common tools and services that offer the same capabilities. It lets users choose among options and creates competition among service providers. We’ve just updated the CEP draft based on your comments. For the rest, please feel free to keep contributing. A good place to start implementing this would be in the ts‑sdk, where we can begin the implementation and write tests. Let me know if you have any doubts.

[abhayguptas]

Thank you, this is very helpful. I took a look through the SDK structure, and I think I now have a clearer idea of where to start.

My current plan is to begin in the server transport and announcement flow, since that seems to be the main place where CEP-15 discovery and interoperability behavior would be surfaced. In particular, I will first look into the NostrServerTransport and the announcement manager path that publishes tools/list events, because that seems like the natural integration point for schema-based discovery tags and related tests.

After that, I plan to trace how tools/list responses are passed through the SDK so I can understand the right place to add or validate common-schema metadata in a way that stays consistent with the updated CEP draft. I will also review the existing CEP-8 tag handling as a reference pattern, since it looks like a good example of how protocol-specific announcement metadata is already integrated.

I will keep reading through the transport/tests and will follow up once I have a more concrete implementation direction or if I run into any doubts.

[DevAnuragT]

Hi, I've been going through the CEP-15 draft and the ts-sdk structure, and noticed PR #37 is intentionally scoped to just the normalization and hashing primitives.

I wanted to ask about the transport-side integration that comes next. My understanding is the remaining work involves:

• injecting _meta["io.contextvm/common-schema"].schemaHash into tools/list responses in NostrServerTransport

• adding i/k discovery tags to kind:11317 announcement events

• end-to-end tests verifying a client can discover and switch between two servers that implement the same schema

Is that the right next area to focus on, or is there a different priority? Happy to take a stab at this part if it's still open.

[krishvsoni]

Hi @ContextVM-org, I've been reading through the CEP-15 draft and tracing the
announcement flow in the SDK. I wanted to flag an implementation detail and
offer to contribute on the parts that aren't covered yet.

Announcement content vs direct response consistency

When publishAnnouncementEvent() publishes a kind:11317 tools/list event, it
serializes the JSON-RPC result directly into the event content via
JSON.stringify(result). But the _meta.schemaHash injection being discussed
for handleResponse() only affects direct client responses — it doesn't touch
the announcement path. This means a client reading a kind:11317 event from a
relay would see tool definitions without _meta.schemaHash, while a client
making a direct tools/list call would see them with it.

To keep both paths consistent, the _meta injection should happen inside
handleAnnouncementResponse() before the result is passed to
publishAnnouncementEvent(), not just in the direct response path. This way
the announcement event content and the direct response both carry the same
schema metadata.

Existing SDK infrastructure that CEP-15 can reuse

Looking at the SDK, two things already exist that could simplify the first
integration:

1. setAnnouncementExtraTags() already supports injecting custom discovery
   tags into server announcements and first-response discovery (there's even a
   test for ['custom_discovery', 'supported'] in the client transport tests).
   CEP-15 i/D tags could use this path as a first step without modifying
   AnnouncementMapping.

2. getTagValues(tags, name) in src/core/utils/utils.ts already extracts
   all values for a given tag name from a Nostr event. A client-side
   extractSchemaHashes(event) is essentially getTagValues(event.tags, 'i').

Where I'd like to contribute

Rather than more architecture discussion, I think the most useful next step is
writing concrete artifacts:

• Reference JSON Schema definitions for 3-5 common tool categories (search,
  translation, weather) as described in the CEP-15 project scope
• A conformance test that creates two servers with the same tool schema,
  verifies they produce identical schema hashes via computeCommonSchemaHash()
  from feat(core): add CEP-15 common schema helpers sdk#37 (comment) , and shows a client can call both identically
• A minimal proof-of-concept wiring the schema hash into an announcement event
  using the existing setAnnouncementExtraTags() path

Happy to start on any of these if they'd be useful.

[sagar-h007]

I’ve been going through the CEP-15 draft and tracing the SDK flow, and I think a key next step is ensuring consistent schema handling across both direct responses and announcement events.

From what I can see:

• tools/list responses flow through handleResponse() in nostr-server-transport.ts
• announcement events (kind:11317) are produced via publishAnnouncementEvent() in announcement-manager.ts, where the result is serialized directly

Right now, the SDK doesn’t implement canonical schema hashing yet, so neither path includes _meta.schemaHash. But structurally, once CEP-15 is added, these two paths can easily diverge if schema enrichment is applied in only one place.

To avoid that, I’d propose introducing a shared transformation step, something like:

• a utility (e.g. canonical-schema.ts) that:
• canonicalizes { name, inputSchema } using RFC 8785
• computes schemaHash
• injects _meta["io.contextvm/common-schema"]
• then applying this once before serialization in both:
• handleResponse() (direct responses)
• publishAnnouncementEvent() (announcements)

This avoids duplicating logic and guarantees that discovery (CEP-6) and direct RPC views of a tool stay consistent.

For CEP-15 discovery tags, it seems like setAnnouncementExtraTags() can be reused for I/D tags on announcements, though we may still need a small extension if similar metadata is expected in direct responses.

One thing I wanted to clarify:-
Should the canonical hash include only { name, inputSchema }, or also fields like description?

My intuition is to exclude description, since it’s non-functional and would cause unnecessary hash divergence across otherwise compatible providers, but I wanted to confirm the intended boundary for “schema equivalence”.

If this direction sounds reasonable, I can start with:

• a shared canonicalization + hashing utility in core
• wiring it into both response and announcement paths
• a small test showing two servers with identical schemas produce identical hashes and are interchangeable

This seems like a minimal but meaningful step toward making schema-based discovery actually reliable.

[ContextVM-org]

@DevAnuragT The implementation of this issue in the ts‑sdk has already been taken by @abhayguptas. On the other hand, “end‑to‑end tests verifying that a client can discover and switch between two servers that implement the same schema” are not necessary.

[ContextVM-org]

@krishvsoni Your comment is correct, but the implementation isn’t finished yet, so it will be added as it progresses.

Reference JSON‑Schema definitions for 3–5 common tool categories (search, translation, weather) as described in the CEP‑15 project scope

This doesn’t make sense; the goal is not to prescribe schema hashes in the specification.

[ContextVM-org]

@sagar-h007 This issues is already being addressed by @abhayguptas In the other hand seems that your comments are based in a previous draft of the spec. Some of your doubts have been already attached, like the inclusion of the description field in the hash

[DevAnuragT]

@DevAnuragT The implementation of this issue in the ts‑sdk has already been taken by @abhayguptas. On the other hand, “end‑to‑end tests verifying that a client can discover and switch between two servers that implement the same schema” are not necessary.

Thanks for the clarification and I'll focus on the spec refinement and reference examples side then.