Introduction

Upjack lets you build AI-powered applications by describing your domain instead of writing code. You write a JSON Schema for your data and Markdown for your domain expertise. Upjack gives you entity management, validation, search, and a complete MCP server — automatically.

from upjack import UpjackApp

app = UpjackApp.from_manifest("manifest.json")

contact = app.create_entity("contact", {"name": "Alice", "email": "alice@example.com"})
results = app.search_entities("contact", query="alice")

No API code. No database. No deployment config.

What You Get

For each entity you define, Upjack provides:

• 6 MCP tools per entity — create_contact, get_contact, update_contact, list_contacts, search_contacts, delete_contact
• Schema validation at every write — invalid data never hits storage
• Type-prefixed IDs — ct_01HZ3QKB... tells you it’s a contact at a glance
• Full-text search across all string fields
• JSON file storage — plain files in a git-friendly directory structure
• Skills as resources — your Markdown expertise files are served to the agent via upjack://skills/*

Define a contact entity schema and a lead-qualification skill in Markdown, and your AI agent immediately knows how to create contacts, qualify leads, and follow up — from two files.

Key Concepts

Entity A typed data record with a JSON Schema. Every entity gets a type-prefixed ULID (for example, ct_01HZ3QKB... for contacts, dl_01HZ4RMN... for deals). Entities are stored as individual JSON files and validated at write time.

Skill A Markdown document encoding domain expertise — scoring rubrics, decision criteria, procedures. The AI agent reads skills and applies them through reasoning, the same way a new hire reads an onboarding doc.

Manifest A JSON declaration that wires entities to skills, defines hooks (react to data changes), schedules (cron triggers), views (named queries), and bundle dependencies (external tools declared by capability alias).

Bundle Dependency An external tool provider declared by alias (for example, email) with a compatibility contract (tools_used array). Switch providers by changing one line — skills and schemas stay the same.

Three Tiers

Upjack meets you where you are. Most apps never leave Tier 1.

Tier	What You Write	What Upjack Provides
Schemas + Skills	JSON Schema + Markdown	Entity management, storage, validation
MCP Server	create_server(manifest)	Full MCP server with CRUD tools, resources
Custom Server	Python MCP server + custom logic	Entity management + your custom tools

At the first tier, you write only declarative files and get a working application. At the second tier, a single function call wraps everything in an MCP server:

from upjack.server import create_server

mcp = create_server("manifest.json")
mcp.run()
# Tools: create_contact, get_contact, update_contact, list_contacts, search_contacts, delete_contact

At the third tier, you build a custom MCP server in Python and use Upjack’s entity management alongside your own tools.

Prerequisites

You do not need deep knowledge of these to get started, but they are helpful context:

Concept	What It Is	Learn More
JSON Schema	A standard for describing the shape of JSON data. Upjack uses it to define what each entity looks like.	Getting Started
MCP	Model Context Protocol — a standard that lets AI agents call tools and read resources. Upjack can expose your app as an MCP server so agents can interact with it.	Introduction
MCPB	MCP Bundle — a packaging format for distributing MCP servers. Upjack apps use the MCPB manifest format, with upjack-specific config in a _meta extension field.	Spec
ULID	Universally Unique Lexicographically Sortable Identifier — like a UUID but sortable by creation time. Upjack uses prefixed ULIDs as entity IDs.	Spec

Next Steps

• Quick Start — Install Upjack, scaffold an app, define an entity, and run it in under 5 minutes
• Build a Todo App — A step-by-step tutorial walking through a complete application
• Architecture — How Upjack works under the hood