upjack

Upjack exposes an MCP server that lets an AI agent interact with your domain model through standard MCP tools. Define an entity schema and a domain-specific set of skills in Markdown, and Upjack generates the CRUD toolset for that entity (create_<entity>, get_<entity>, update_<entity>, list_<entities>, search_<entities>, delete_<entity>). Data is validated against JSON Schema on every write, and IDs are prefixed (e.g., nt_ for notes) to convey type at a glance. The server serves both the domain knowledge (via Markdown skills and context) and the governance hooks that allow an agent to manage entities, search data, and apply domain rules. You can run the server in Python (server.py) or in TypeScript/Node.js (server.ts) depending on your stack. The included examples (Todo, CRM, Research Assistant) show how to scaffold an app and connect an agent (Claude, Cursor, Codex, etc.) to the MCP server to perform full CRUD with built-in search and schema validation. To use it, start the server in your app directory, then issue MCP calls such as create_<entity>, list_<entities>, search_<entities>, get_<entity>, update_<entity>, and delete_<entity> via your agent or client integration. The server communicates over stdio, so it can be connected to any MCP client that speaks the protocol, enabling seamless tool invocation and resource access for your agent-driven applications.

Prerequisites:

• Python 3.13+ (for the Python/uv runtime) or Node.js 18+ (if you prefer the TS/Node runtime).
• Basic Git and shell access.

Option A: Python/uv runtime (recommended when using server.py)

1. Create a Python environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate  # Windows

2. Install Upjack with MCP support (PyPI):

pip install upjack
pip install "upjack[mcp]"

3. Run the MCP server (from the app directory containing server.py):

python server.py

Option B: Node.js/TypeScript runtime (server.ts)

1. Ensure Node.js v18+ is installed.
2. Install Upjack with MCP support:

npm install upjack

3. Run the TypeScript server (from the app directory):

npx tsx server.ts

If you are starting from a scaffolded app, you can also install prerequisites and run any provided example (Todo, CRM, or Research Assistant) using the instructions above. The server communicates over stdio, so you’ll interact with it through MCP clients or tooling that understands the MCP protocol.

Tips and considerations:

• The MCP server serializes data to a JSON file storage layout that is Git-friendly, making it easy to version and merge changes.
• Entity IDs are ULID-prefixed (e.g., nt_...) to convey the type and creation order.
• Upjack exposes per-entity CRUD tools automatically based on your JSON Schema and manifest configuration. You can extend the domain by adding Markdown-based skills and domain knowledge files that the agent can read at runtime.
• If you modify the manifest or schemas, re-run any scaffold or build steps described in the Quick Start to keep tools in sync.
• For Python, ensure your environment has the required dependencies (upjack and upjack[mcp]). For Node.js, you may use tsx to run TypeScript server files directly.
• The server operates over stdio; ensure your MCP client is configured to connect via the standard input/output streams.