Skip to content

Commit aa3be6a

Browse files
markraimarkrai
committed
compliance with MCP specifications
Signed-off-by: Mark Rai <markraidc@gmail.com>
1 parent f256f56 commit aa3be6a

7 files changed

Lines changed: 1014 additions & 50 deletions

File tree

‎API.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,114 @@ Responses use `Cache-Control: no-store` and `Content-Type: application/json; cha
3939

4040
---
4141

42+
## JSON-RPC MCP endpoint (spec-compatible)
43+
44+
In addition to the **`/mcp`** HTTP interface above, Scrumboy exposes a Model Context Protocol (MCP) oriented endpoint that speaks **JSON-RPC 2.0**. This is a **separate** transport from the legacy `{ "tool", "input" }` POST body; both are mounted on the same MCP adapter.
45+
46+
**Endpoint:** `POST /mcp/rpc` (trailing slash `/mcp/rpc/` is accepted).
47+
48+
**Intended use:** MCP-style clients (e.g. Claude Desktop, agent frameworks) that expect JSON-RPC framing.
49+
50+
### Protocol
51+
52+
- Uses **JSON-RPC 2.0**.
53+
- **`jsonrpc`:** must be the string `"2.0"`.
54+
- **`method`:** required (string).
55+
- **`id`:** required for **requests** that expect a JSON body (`initialize`, `tools/list`, `tools/call`). Omitted for **notifications** (see below). For **parse errors**, the response uses `"id": null` per JSON-RPC.
56+
- **`params`:** optional for `initialize` and `tools/list` (may be omitted or an object). For **`tools/call`**, `params` must be a JSON object (see below).
57+
58+
**Non-POST** requests receive a JSON-RPC error (`id` null). **HTTP status** for normal JSON-RPC replies is **200** for both success and error objects in the body (errors are not signaled only by HTTP status). The **`notifications/initialized`** (or **`initialized`**) notification is answered with **204 No Content** and an empty body.
59+
60+
**Example request:**
61+
62+
```json
63+
{
64+
"jsonrpc": "2.0",
65+
"id": 1,
66+
"method": "initialize",
67+
"params": {}
68+
}
69+
```
70+
71+
### Supported methods
72+
73+
**`initialize`** — Initial handshake. Requires `id`. Returns `protocolVersion` (currently `2024-11-05`), `capabilities`, `serverInfo`, and optional `instructions`. `params` may be omitted or empty.
74+
75+
**`notifications/initialized`** or **`initialized`** — Client acknowledgment after `initialize`. Must be sent **without** `id` (notification). Server responds with **204** and no JSON body. If an `id` is present, the server rejects the call.
76+
77+
**`tools/list`** — Requires `id`. Returns `{ "tools": [ ... ] }`. Each entry has `name`, `description`, and `inputSchema` (JSON Schema object). **Today** the list includes **four** tools with full schemas (`projects.list`, `todos.create`, `todos.get`, `todos.update`); more entries will be added over time. **`tools/list` does not require a prior `initialize`.**
78+
79+
**`tools/call`** — Invokes a tool by name. Requires `id` and a **`params` object** containing:
80+
81+
- **`name`** (string, required): exact registered tool name (same names as `POST /mcp`’s `tool` field).
82+
- **`arguments`** (object, optional): tool input; if omitted, treated as `{}`.
83+
84+
**`tools/call` uses the same tool registry as `POST /mcp`**, so any implemented tool may be invoked even if it does not yet appear in `tools/list`. For tools that **do** appear in `tools/list`, the server performs a **lightweight check** that JSON Schema `required` top-level properties are present in `arguments` before calling the handler; full JSON Schema validation is not performed. Unknown tool names yield JSON-RPC **`method not found`** (`-32601`); optional `error.data` may include `{ "name": "<tool>" }`.
85+
86+
**Example `tools/call`:**
87+
88+
```json
89+
{
90+
"jsonrpc": "2.0",
91+
"id": 2,
92+
"method": "tools/call",
93+
"params": {
94+
"name": "todos.create",
95+
"arguments": {
96+
"projectSlug": "my-project",
97+
"title": "New todo"
98+
}
99+
}
100+
}
101+
```
102+
103+
### Response format
104+
105+
All JSON-RPC **responses with a body** include `"jsonrpc": "2.0"` and preserve the request `id` (except parse errors → `id: null`). This endpoint **does not** use the legacy `ok` / `data` / `meta` envelope.
106+
107+
**Success (`tools/call` result shape):**
108+
109+
```json
110+
{
111+
"jsonrpc": "2.0",
112+
"id": 2,
113+
"result": {
114+
"content": [
115+
{
116+
"type": "json",
117+
"json": {}
118+
}
119+
]
120+
}
121+
}
122+
```
123+
124+
The `json` object is the tool’s result value (same conceptual payload as legacy `data`, including nested shapes such as `{ "todo": { ... } }` where the tool returns that).
125+
126+
**Error:**
127+
128+
```json
129+
{
130+
"jsonrpc": "2.0",
131+
"id": 2,
132+
"error": {
133+
"code": -32602,
134+
"message": "invalid params"
135+
}
136+
}
137+
```
138+
139+
**Typical JSON-RPC error codes:** `-32700` parse error, `-32600` invalid request, `-32601` method/tool not found, `-32602` invalid params / validation, `-32603` internal error. The `message` string is human-readable; some errors include optional `data`.
140+
141+
### Notes
142+
143+
- **Stateless HTTP:** there is no server-side session between requests; behavior does not depend on having called `initialize` first for `tools/list` or `tools/call`.
144+
- **`initialize` is supported** for clients that expect the handshake; it is **not** enforced before discovery or tool calls on this server.
145+
- **Authentication** follows the same rules as **`/mcp`** (session cookie and Bearer token in `full` mode; anonymous mode boundary unchanged). See [Authentication and capability model](#authentication-and-capability-model).
146+
- The **legacy `GET` / `POST /mcp`** endpoint remains **unchanged** and is documented in the sections above.
147+
148+
---
149+
42150
## Response envelopes
43151

44152
### Success

‎CHANGELOG.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,31 @@
11
# Changelog
22

3-
> **Upgrades:** No breaking changes in **3.7.x** unless noted below.
3+
> **Upgrades:** No breaking changes in **3.7.x** / **3.8.x** unless noted below.
44
55

6+
## [3.8.0] - 2026-04-03
7+
8+
### Features
9+
10+
- **MCP JSON-RPC: `tools/list` and `tools/call`** on **`POST /mcp/rpc`** — Completes the spec-oriented MCP loop alongside existing **`initialize`** / **`notifications/initialized`**. **`tools/list`** returns tools with **`name`**, **`description`**, and **`inputSchema`** (JSON Schema with **`required`** and tight objects where defined); the catalog starts with four tools (**`projects.list`**, **`todos.create`**, **`todos.get`**, **`todos.update`**) and will grow over time. **`tools/call`** accepts **`params.name`** and **`params.arguments`**, reuses the same tool handlers as legacy **`POST /mcp`**, and returns success as **`result.content[]`** with **`type: "json"`** and the tool payload in **`json`**. Discovery and invocation are **stateless** (no **`initialize`** required for **`tools/list`** or **`tools/call`**). Errors use JSON-RPC codes (**`-32601`** unknown tool, **`-32602`** invalid params / validation, **`-32603`** internal); unknown tools may include **`error.data`** with **`name`**.
11+
12+
### Improvements
13+
14+
- **Catalog `required` handling** — Pre-call checks read the **`required`** array whether it is stored as **`[]string`** (in-memory catalog) or **`[]any`** (e.g. after JSON round-trip), avoiding silent skips.
15+
- **`tools/call` shape errors** — Clearer **`missing params`** / **`missing params.name`** messages for invalid requests.
16+
17+
### Documentation
18+
19+
- **`API.md`** — New **JSON-RPC MCP endpoint (spec-compatible)** section for **`POST /mcp/rpc`**: protocol rules, supported methods, response shapes, auth (same as **`/mcp`**), and how this differs from the legacy **`/mcp`** envelope.
20+
- **`README.md`** — **MCP (JSON-RPC) for AI agents** subsection with **`curl`** examples (**`initialize`**, **`tools/list`**, **`tools/call`**), pointer to **`API.md`**, and notes on HTTP JSON-RPC vs stdio MCP clients.
21+
22+
---
23+
624
## [3.7.8] - 2026-04-03
725

826
### Features
927

10-
- **MCP JSON-RPC (Phase 1)** - New **`POST /mcp/rpc`** endpoint using **JSON-RPC 2.0** alongside the existing **`/mcp`** `{ "tool", "input" }` API (unchanged). Supports **`initialize`** (protocol version **2024-11-05**, `capabilities.tools`, `serverInfo`), **`notifications/initialized`** and **`initialized`** as notifications (**204** empty body), and spec error codes (e.g. **-32601** method not found). **`tools/list`** and **`tools/call`** are planned for a follow-up release.
28+
- **MCP JSON-RPC (Phase 1)** - New **`POST /mcp/rpc`** endpoint using **JSON-RPC 2.0** alongside the existing **`/mcp`** `{ "tool", "input" }` API (unchanged). Supports **`initialize`** (protocol version **2024-11-05**, `capabilities.tools`, `serverInfo`), **`notifications/initialized`** and **`initialized`** as notifications (**204** empty body), and spec error codes (e.g. **-32601** method not found). **`tools/list`** and **`tools/call`** added in **3.8.0**.
1129

1230
---
1331

‎README.md‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
<p align="center">
22
<img width="372" src="internal/httpapi/web/githublogo.png" alt="scrumboy logo" />
33
<br />
4-
<img src="https://img.shields.io/badge/version-v3.7.8-blue" alt="version" />
4+
<img src="https://img.shields.io/badge/version-v3.8.0-blue" alt="version" />
55
<a href="LICENSE">
66
<img src="https://img.shields.io/badge/license-AGPL--v3-orange" alt="license" />
77
</a>
88
</p>
99

10-
#### Self-hosted project management & issue-tracking solution + instant shareable & customizable boards + realtime collaboration, automation, API access and MCP support
10+
#### Self-hosted project management & issue-tracking solution + instant shareable & customizable boards + realtime collaboration, automation, API access and MCP-compatible client support
1111

1212

1313
<img width="2975" height="1078" alt="image" src="internal/httpapi/web/github_preview.jpg" />
@@ -116,9 +116,9 @@ Simplicity of a light Kanban, with the power of structured systems: Roles, sprin
116116

117117
## Integrations & API Access
118118

119-
Scrumboy supports API access tokens for automation, integrations, and AI agents.
119+
Scrumboy supports API access tokens for automation, integrations, and programmatic MCP access (legacy HTTP and JSON-RPC — see below).
120120

121-
You can create a token from the API and use it to call MCP directly — no browser session or cookies required.
121+
You can create a token from the API and use it to call MCP endpoints directly — no browser session or cookies required.
122122

123123
**Create a token (requires login session):**
124124

@@ -139,11 +139,62 @@ curl -X POST http://localhost:8080/mcp \
139139
-H "Authorization: Bearer sb_your_token_here" \
140140
-d '{"tool":"projects.list","input":{}}'
141141
```
142+
143+
### MCP (JSON-RPC) for AI agents
144+
145+
Scrumboy exposes a **Model Context Protocol (MCP) compatible JSON-RPC endpoint** for AI agents (Claude, etc.) and MCP-compatible clients.
146+
147+
**Endpoint:** `POST /mcp/rpc`
148+
149+
This is separate from the `/mcp` HTTP endpoint above and follows **JSON-RPC 2.0** (`initialize`, `tools/list`, `tools/call`, etc.). See [`API.md`](API.md) for full detail.
150+
151+
#### Example: `initialize`
152+
153+
```bash
154+
curl -X POST http://localhost:8080/mcp/rpc \
155+
-H "Content-Type: application/json" \
156+
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
157+
```
158+
159+
#### Example: list tools
160+
161+
```bash
162+
curl -X POST http://localhost:8080/mcp/rpc \
163+
-H "Content-Type: application/json" \
164+
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
165+
```
166+
167+
#### Example: call a tool
168+
169+
```bash
170+
curl -X POST http://localhost:8080/mcp/rpc \
171+
-H "Content-Type: application/json" \
172+
-H "Authorization: Bearer sb_your_token_here" \
173+
-d '{
174+
"jsonrpc":"2.0",
175+
"id":3,
176+
"method":"tools/call",
177+
"params":{
178+
"name":"todos.create",
179+
"arguments":{
180+
"projectSlug":"my-project",
181+
"title":"Created via MCP"
182+
}
183+
}
184+
}'
185+
```
186+
187+
**Notes**
188+
189+
- Compatible with MCP clients that support **HTTP JSON-RPC** to this URL.
190+
- Some MCP clients expect **stdio**-based servers — those are **not** supported here.
191+
- Authentication works via **session cookie** or **Bearer** token (same rules as `/mcp`).
192+
142193
This enables:
143194

144195
- CLI usage
145196
- CI/CD automation
146-
- AI agents (Claude, etc.)
197+
- AI agents and MCP clients (use **`POST /mcp/rpc`** for JSON-RPC; **`POST /mcp`** remains available for the legacy `{ "tool", "input" }` envelope)
147198
- Scripting/integrations without login flows
148199

149200

0 commit comments

Comments
 (0)