Skip to content

armgit / kanzo

Public Imported from GitHub
0

Self-hosted, sharable kanban for humans and agents. One 4.7 MB binary, 5 MB of RAM, 10 to 60 tokens per agent reply, starts in 3 ms, zero setup.

Serve MCP over HTTP at /mcp

emanuele-em7008a55339dc
diff --git a/Cargo.lock b/Cargo.lock
index 13302c4..52ebbc2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -67,6 +67,17 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+[[package]]
+name = "async-trait"
+version = "0.1.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
[[package]]
name = "atomic-waker"
version = "1.1.2"
@@ -171,6 +182,17 @@ version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+[[package]]
+name = "chacha20"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "rand_core",
+]
+
[[package]]
name = "chrono"
version = "0.4.45"
@@ -235,6 +257,15 @@ version = "0.8.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+[[package]]
+name = "cpufeatures"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
+dependencies = [
+ "libc",
+]
+
[[package]]
name = "darling"
version = "0.24.1"
@@ -448,6 +479,7 @@ dependencies = [
"cfg-if",
"libc",
"r-efi",
+ "rand_core",
]
[[package]]
@@ -633,6 +665,7 @@ dependencies = [
"serde_json",
"tempfile",
"tokio",
+ "tokio-util",
"toml",
]
@@ -810,6 +843,23 @@ version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+[[package]]
+name = "rand"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af"
+dependencies = [
+ "chacha20",
+ "getrandom",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
[[package]]
name = "redox_syscall"
version = "0.5.18"
@@ -855,20 +905,29 @@ version = "3.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ece64e19631fc38758181e637c15509a2c2709ee53bfde1e1d58f9dc991f919e"
dependencies = [
+ "async-trait",
"base64",
+ "bytes",
"chrono",
"futures",
+ "http",
+ "http-body",
+ "http-body-util",
"indexmap",
"libc",
"pastey",
"pin-project-lite",
+ "rand",
"rmcp-macros",
"schemars",
"serde",
"serde_json",
+ "sse-stream",
"thiserror",
"tokio",
+ "tokio-stream",
"tokio-util",
+ "tower-service",
"tracing",
"uuid",
]
@@ -1101,6 +1160,19 @@ dependencies = [
"rsqlite-vfs",
]
+[[package]]
+name = "sse-stream"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c25ac7aff0abd1dbc474536e40416e1102c7dd9bfba0b9861c6d357f835dcfb4"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "http-body",
+ "http-body-util",
+ "pin-project-lite",
+]
+
[[package]]
name = "strsim"
version = "0.11.1"
@@ -1196,6 +1268,17 @@ dependencies = [
"syn 3.0.9",
]
+[[package]]
+name = "tokio-stream"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+ "tokio",
+]
+
[[package]]
name = "tokio-util"
version = "0.7.20"
diff --git a/Cargo.toml b/Cargo.toml
index bb8c60a..0c1d729 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -16,12 +16,13 @@ anyhow = "1.0.104"
axum = "0.8.9"
clap = { version = "4.6.7", features = ["derive"] }
dirs = "7.0.0"
-rmcp = { version = "=3.7.0", features = ["server", "transport-io", "macros"] }
+rmcp = { version = "=3.7.0", features = ["server", "transport-io", "transport-streamable-http-server", "macros"] }
rusqlite = { version = "0.41.0", features = ["bundled"] }
schemars = "1.2.3"
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.154"
tokio = { version = "1.54.1", features = ["full"] }
+tokio-util = "0.7.20"
toml = "1.1.8"
[dev-dependencies]
diff --git a/README.md b/README.md
index f754b6c..8bcc5bf 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,14 @@ codex mcp add kanzo -- kanzo mcp # Codex
Any other MCP client works too: the command is `kanzo` with the argument `mcp`. GUI apps such as Raycast may not see Homebrew's `PATH`, so give them the full path from `which kanzo`.
+**Over HTTP.** Clients that can't start a local program can use the running board instead, at `http://localhost:4242/mcp`:
+
+```sh
+claude mcp add --transport http kanzo http://localhost:4242/mcp
+```
+
+Over HTTP Kanzo can't see which folder the agent works in, so the agent has to name the project. The endpoint answers only on localhost; turn it off with `mcp_http = false` in `config.toml`.
+
Then ask your agent things like *"take the next task from kanzo and do it"*, or *"add a kanzo task for the flaky login test"*.
### Tools agents get
@@ -77,6 +85,7 @@ Everything is in `~/kanzo`. Use another folder with `--home <dir>` or `KANZO_HOM
```toml
port = 4242
statuses = ["todo", "doing", "review", "done"]
+mcp_http = true
```
New tasks go in the first column; tasks in the last one count as done.
@@ -129,8 +138,8 @@ The code is small on purpose:
| `src/home.rs` | Data folder and `config.toml` |
| `src/schema.sql` | The database schema |
| `src/store.rs` | All SQL |
-| `src/mcp.rs` | The MCP tools (`rmcp`, pinned on purpose: it still changes often) |
-| `src/web.rs` | The board's HTTP API |
+| `src/mcp.rs` | The MCP tools, over stdio and HTTP (`rmcp`, pinned on purpose: it still changes often) |
+| `src/web.rs` | The board's HTTP API, and `/mcp` |
| `src/index.html` | The whole board UI: plain HTML, CSS and JavaScript, built into the binary |
| `src/sync.rs` | `kanzo sync` |
| `src/export.rs` | `kanzo export` |
diff --git a/src/home.rs b/src/home.rs
index 0e7e07e..ebe3aed 100644
--- a/src/home.rs
+++ b/src/home.rs
@@ -18,6 +18,10 @@ port = 4242
# Board columns, left to right. New tasks go in the first one;
# tasks in the last one count as done.
statuses = ["todo", "doing", "review", "done"]
+
+# Also serve MCP over HTTP at http://localhost:<port>/mcp, for agents
+# that cannot start `kanzo mcp` themselves.
+mcp_http = true
"#;
const GITIGNORE: &str = "\
@@ -35,11 +39,16 @@ kanzo.lock
pub struct Config {
pub port: u16,
pub statuses: Vec<String>,
+ pub mcp_http: bool,
}
impl Default for Config {
fn default() -> Self {
- Self { port: DEFAULT_PORT, statuses: ["todo", "doing", "review", "done"].map(String::from).to_vec() }
+ Self {
+ port: DEFAULT_PORT,
+ statuses: ["todo", "doing", "review", "done"].map(String::from).to_vec(),
+ mcp_http: true,
+ }
}
}
@@ -150,6 +159,7 @@ mod tests {
assert!(dir.join("kanzo.db").exists());
assert_eq!(home.config.port, DEFAULT_PORT);
assert_eq!(home.config.statuses, ["todo", "doing", "review", "done"]);
+ assert!(home.config.mcp_http);
}
#[test]
diff --git a/src/mcp.rs b/src/mcp.rs
index 4618ba9..a95bb8b 100644
--- a/src/mcp.rs
+++ b/src/mcp.rs
@@ -1,4 +1,5 @@
-//! `kanzo mcp`: the board as MCP tools over stdio. Replies are short plain text to save agents' tokens.
+//! The board as MCP tools: over stdio for `kanzo mcp`, and over HTTP at `/mcp` of the board.
+//! Replies are short plain text to save agents' tokens.
use std::path::PathBuf;
use std::process::Command;
@@ -8,9 +9,12 @@ use anyhow::Result;
use rmcp::handler::server::router::tool::ToolRouter;
use rmcp::handler::server::wrapper::Parameters;
use rmcp::model::{CallToolResult, ContentBlock, Implementation, ServerCapabilities, ServerConfig};
+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};
use rmcp::{ErrorData, Peer, RoleServer, ServerHandler, ServiceExt, tool, tool_handler, tool_router};
use schemars::JsonSchema;
use serde::Deserialize;
+use tokio_util::sync::CancellationToken;
use crate::home::Home;
use crate::store::{self, Comment, Error, Project, Store, Task, TaskPatch};
@@ -20,18 +24,43 @@ Tasks are written project#id, like api#12. When you leave out `project`, Kanzo u
linked to the GitHub repo of the folder you are working in. A good loop: next_task to pick up work, \
add_comment to report what you did, then update_task to move it to review.";
+const HTTP_INSTRUCTIONS: &str = "Kanzo is the user's kanban board, shared by all their projects. \
+Tasks are written project#id, like api#12. Over HTTP Kanzo cannot see which folder you work in, so \
+pass `project` (see list_projects). A good loop: next_task to pick up work, add_comment to report \
+what you did, then update_task to move it to review.";
+
+/// `kanzo mcp`: one agent on stdin and stdout, in the folder it started us in.
pub async fn serve(home: Home) -> Result<()> {
let cwd = std::env::current_dir().unwrap_or_default();
let repos = git_repos(&cwd);
- let server = Kanzo { ctx: Arc::new(Ctx { home, cwd, repos }), tool_router: Kanzo::tool_router() };
+ let server = Kanzo { ctx: Arc::new(Ctx { home, cwd: Some(cwd), repos }), tool_router: Kanzo::tool_router() };
let service = server.serve(rmcp::transport::stdio()).await?;
service.waiting().await?;
Ok(())
}
+/// MCP over HTTP, mounted at `/mcp` by the board. Only browsers on the board's own origin may call it.
+pub fn http_service(
+ home: Home,
+ port: u16,
+ shutdown: CancellationToken,
+) -> StreamableHttpService<Kanzo, LocalSessionManager> {
+ let ctx = Arc::new(Ctx { home, cwd: None, repos: Vec::new() });
+ let config = StreamableHttpServerConfig::default()
+ .with_allowed_hosts(["localhost", "127.0.0.1"])
+ .with_allowed_origins([format!("http://localhost:{port}"), format!("http://127.0.0.1:{port}")])
+ .with_cancellation_token(shutdown);
+ StreamableHttpService::new(
+ move || Ok(Kanzo { ctx: ctx.clone(), tool_router: Kanzo::tool_router() }),
+ Default::default(),
+ config,
+ )
+}
+
struct Ctx {
home: Home,
- cwd: PathBuf,
+ /// The agent's working folder; `None` over HTTP, where we cannot know it.
+ cwd: Option<PathBuf>,
/// GitHub repos (`owner/repo`) of the git remotes of `cwd`.
repos: Vec<String>,
}
@@ -49,7 +78,15 @@ impl Ctx {
}
let known: Vec<String> = store.list_projects()?.into_iter().map(|p| p.slug).collect();
let known = known.join(", ");
- let cwd = self.cwd.display();
+ let Some(cwd) = &self.cwd else {
+ let msg = if known.is_empty() {
+ "There are no projects yet. Create one with create_project.".to_string()
+ } else {
+ format!("Pass `project` (one of: {known}); over HTTP Kanzo cannot see which folder you work in.")
+ };
+ return Err(Error::NotFound(msg));
+ };
+ let cwd = cwd.display();
let msg = match (self.repos.first(), known.is_empty()) {
(Some(repo), false) => format!(
"No project is linked to {repo} (the git remote of {cwd}). Pass `project` (one of: {known}), \
@@ -367,7 +404,7 @@ impl ServerHandler for Kanzo {
fn get_info(&self) -> ServerConfig {
ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
.with_server_info(Implementation::new("kanzo", env!("CARGO_PKG_VERSION")))
- .with_instructions(INSTRUCTIONS)
+ .with_instructions(if self.ctx.cwd.is_some() { INSTRUCTIONS } else { HTTP_INSTRUCTIONS })
}
}
diff --git a/src/web.rs b/src/web.rs
index d104fd6..64d1fa5 100644
--- a/src/web.rs
+++ b/src/web.rs
@@ -1,4 +1,4 @@
-//! `kanzo`: the board page and the small JSON API behind it.
+//! `kanzo`: the board page, the small JSON API behind it, and MCP over HTTP at `/mcp`.
use std::net::SocketAddr;
use std::sync::Arc;
@@ -13,6 +13,7 @@ use axum::{Json, Router};
use serde::{Deserialize, Serialize};
use serde_json::json;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio_util::sync::CancellationToken;
use crate::home::Home;
use crate::store::{self, Error, Store, TaskPatch};
@@ -37,20 +38,29 @@ pub async fn serve(home: Home, port: Option<u16>, open: bool) -> Result<()> {
Err(e) => return Err(e).context(format!("cannot listen on port {port}")),
};
println!("Kanzo board at {url}, data in {}", home.dir.display());
+ if home.config.mcp_http {
+ println!("MCP over HTTP at {url}/mcp");
+ }
if open {
open_browser(&url);
}
- axum::serve(listener, router(home, port))
- .with_graceful_shutdown(async {
+ // Cancelling this also ends open MCP streams, which would otherwise hold up shutdown.
+ let shutdown = CancellationToken::new();
+ axum::serve(listener, router(home, port, shutdown.clone()))
+ .with_graceful_shutdown(async move {
let _ = tokio::signal::ctrl_c().await;
+ shutdown.cancel();
})
.await?;
Ok(())
}
-fn router(home: Home, port: u16) -> Router {
- Router::new()
- .route("/", get(|| async { Html(INDEX) }))
+fn router(home: Home, port: u16, shutdown: CancellationToken) -> Router {
+ let mut app = Router::new();
+ if home.config.mcp_http {
+ app = app.nest_service("/mcp", crate::mcp::http_service(home.clone(), port, shutdown));
+ }
+ app.route("/", get(|| async { Html(INDEX) }))
.route("/api/ping", get(|| async { "kanzo" }))
.route("/api/changes", get(changes))
.route("/api/board", get(board))