Mini agent toy project with deepseek-reasoner and mcp-tools support.
PioClaw is a lightweight agent framework built with Deno. It integrates DeepSeek Reasoner LLM and Model Context Protocol (MCP) tools, providing both CLI and web interface for interactive AI workflows.
- DeepSeek Reasoner model with streaming reasoning
- MCP tools integration (PDF tools, PowerShell, etc.)
- Event-driven message dispatcher
- Extensible callback system
- CLI and web server interfaces
- Session management with memory
graph TB
subgraph "Input Sources"
CLI[CLI Interface]
WEB[Web Server]
end
subgraph "Core Engine"
DISP[Dispatcher]
AGENT[Agent Loop]
MEM[Memory Manager]
end
subgraph "Handlers"
USER[UserReq Handler]
LLM[LLMStreamRes Handler]
TOOL[ToolCallReq Handler]
PARSE[ParseStream Handler]
end
subgraph "LLM & Tools"
DEEPSEEK[DeepSeek API]
MCP[MCP Servers]
end
CLI --> DISP
WEB --> DISP
DISP --> AGENT
AGENT --> MEM
AGENT --> HANDLERS[Handlers]
USER --> DEEPSEEK
LLM --> PARSE
PARSE --> TOOL
TOOL --> MCP
TOOL --> USER
- Deno 2.x
- DeepSeek API key (set as
DEEPSEEK_API_KEYin.env) - MCP configuration (optional)
# Clone the repo
git clone https://github.com/lithiumfleet/pioclaw.git
cd pioclaw
# Set up environment
touch .env
# Edit .env with your DeepSeek API key# Run example CLI agent
deno task example# Start web server
deno task server
# Open http://localhost:8000The dispatcher handles different message types in the agent loop. Just add any message data type with handlers you want by editing src/handlers/dispatcher.ts.
function YourNewReqDataHandler(data: {anything: any}) {
console.log("hello from new req");
return;
}
// register handlers here
export const dispatcher = {
userreq: createUserReqHandler(),
llmstreamres: createLLMResHandler(),
toolcallreq: createToolCallHandler(),
parsestreamreq: createParseStreamHandler(),
YourNewReqType: YourNewReqDataHandler
};Register (override) custom callbacks for agent events:
import { registerAgentCallbacks } from "@src/handlers/callbacks.ts";
registerAgentCallbacks(
(chunk) => console.log("LLM output:", chunk),
(reasoning) => console.log("Reasoning:", reasoning),
(toolRes) => console.log("Tool result:", toolRes)
);import { initAgent } from "@src/index.ts";
import { memoryManager, type Memory } from "@src/index.ts";
import { registerAgentCallbacks } from "@src/index.ts";
// Create agent loop
const { start, end, input } = initAgent();
// Manage memory
const memory = memoryManager().newMemory();
// Send input
input({ type: "userreq", data: { memory, prompt } });Configure MCP servers in data/mcps.json:
{
"servers": {
"pdf-tools": {
"command": "uv",
"args": ["--directory", "PATH/TO/mcp-pdf-tools", "run", "pdf-tools"]
}
}
}See example/main.ts for CLI implementation and server/app.ts for web server setup.
MIT