apache / apache/pulsar

Add a Model Context Protocol (MCP) server for Apache Pulsar

Open
#26,039 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
15.3k
Forks
3.8k
Avg merge
1d 14h
Merged PRs (30d)
160

Description

**Issue Type:** New Feature
**Priority:** Major
**Labels:** `type/feature`

---

## Background

The Model Context Protocol (MCP) is an open standard that lets AI agents invoke
well-defined tools against a system. An MCP server for Apache Pulsar would allow
operators and AI agents to inspect and manage a Pulsar cluster — producing and
consuming messages, administration, monitoring, and schema operations — through a
standardized protocol. Multiple Apache projects already ship MCP servers, including
Kafka, Spark, Flink, Hive, Ignite, Solr, and Camel.

## Proposal

A new Java module would expose Pulsar operations as MCP tools across four categories:

- **Messaging (`PulsarClient`):** produce a message to a topic; consume N messages
from a subscription (with or without ack); peek the last messages via a `Reader`
without consuming (safe for debugging).
- **Administration (`PulsarAdmin`):** list/create/delete tenants, namespaces, topics
(partitioned and non-partitioned), and subscriptions; reset cursors; unload topics.
- **Monitoring (`PulsarAdmin`):** topic stats (throughput, storage, producer/consumer
counts), per-subscription backlog, broker/cluster health.
- **Schema registry (`PulsarAdmin.schemas()`):** get the current/specified schema of a
topic, upload a schema (Avro/JSON/Protobuf), list schema versions and compatibility.

## Design Notes

The implementation would use the official MCP Java SDK
(`modelcontextprotocol/java-sdk`, tracking the current MCP spec) together with the
`pulsar-client` and `pulsar-client-admin` libraries. Both STDIO and HTTP/SSE
transports would be supported. **Read-only mode is the default; destructive tools
(delete topic/tenant, reset cursor) require an explicit admin mode plus a confirm
flag.** Connection security covers token, OAuth2, and TLS auth, with no hardcoded
secrets, per-tenant/namespace allow/deny lists, payload/count/timeout limits, and
audit logging of every invoked operation. The MCP Java SDK dependency carries an
ASF-compatible license (Apache-2.0 / MIT).

## Scope

The MVP would include monitoring and read-only messaging (`produce`,
`consume`/`peek`, `topics.list`, `topics.stats`, `schema.get`) with comprehensive
testing. Full administration, monitoring, and schema-registry features would follow
in subsequent pull requests.

## Acceptance Criteria

- Builds successfully with Maven and passes checkstyle/spotless and `apache-rat`
(Apache license headers on every file).
- Includes unit tests (mocked `PulsarAdmin`/`PulsarClient`) and integration tests
against a running broker (Testcontainers, `apachepulsar/pulsar`).
- MCP compatibility verified with a real MCP client (MCP Inspector).
- Documentation in the module README and Pulsar docs.

Contributor guide

Open the contributing guide

Research direction

The payload does not name existing Pulsar files or entry points; begin by locating the Maven module structure and reviewing the official MCP Java SDK alongside the pulsar-client and pulsar-client-admin libraries. Start with the MVP monitoring and read-only messaging scope, then use mocked-client unit tests and Testcontainers integration tests. Done means the module builds with the listed checks and documents the feature in its README and Pulsar docs.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend-api-design, distributed-systems, security, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.