research_project_create
Create a research project that persists across sessions. Returns a project_id for subsequent calls. Depth parameter controls exploration from overview (5 docs) to deep (20+ docs with adversarial verification).
Instructions
Create a persistent research project. Returns a project_id that you can pass to all subsequent research_* calls. Projects survive across sessions — open it days later with research_project_continue and you get every prior finding, hypothesis, and open gap. Depth controls how aggressively the synthesizer explores: overview (5 docs), standard (10 docs), deep (20+ docs with adversarial verification).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| userId | No | Owner user_id (matches memory userId). | |
| name | Yes | Short project label. | |
| question | Yes | The central question to investigate. | |
| depth | No | "overview" | "standard" | "deep". Default "standard". |
Implementation Reference
- The handler function for research_project_create. Inserts a new research project into the 'research_projects' table with userId, name, question, and depth (defaulting to 'standard'), then returns the new project_id.
const handleProjectCreate: McpToolHandler = async (args, ctx) => { const pool = (await ensureSchema(ctx)) as any; const userId = String(args.userId ?? ctx.userId); if (!userId) return err('userId required'); const r = await pool.query( `INSERT INTO research_projects (user_id, name, question, depth) VALUES ($1,$2,$3,$4) RETURNING id`, [userId, String(args.name), String(args.question), String(args.depth ?? 'standard')], ); return ok(asText({ success: true, project_id: r.rows[0].id, name: args.name, question: args.question, depth: args.depth ?? 'standard' })); }; - The input schema definition for research_project_create. Defines the tool name, description, and inputSchema with properties: userId (string), name (string, required), question (string, required), depth (string, optional, 'overview'|'standard'|'deep').
name: 'research_project_create', description: 'Create a persistent research project. Returns a project_id that you can pass to all subsequent research_* calls. Projects survive across sessions — open it days later with research_project_continue and you get every prior finding, hypothesis, and open gap. Depth controls how aggressively the synthesizer explores: overview (5 docs), standard (10 docs), deep (20+ docs with adversarial verification).', inputSchema: { type: 'object', properties: { userId: { type: 'string', description: 'Owner user_id (matches memory userId).' }, name: { type: 'string', description: 'Short project label.' }, question: { type: 'string', description: 'The central question to investigate.' }, depth: { type: 'string', description: '"overview" | "standard" | "deep". Default "standard".' }, }, required: ['name', 'question'], }, }, - packages/core/src/mcp/research-tools.ts:230-248 (registration)RESEARCH_TOOLS array entry registering the research_project_create tool. Includes group 'ai', the full definition, and links to the handleProjectCreate handler.
export const RESEARCH_TOOLS: RegisteredTool[] = [ { group: 'ai', definition: { name: 'research_project_create', description: 'Create a persistent research project. Returns a project_id that you can pass to all subsequent research_* calls. Projects survive across sessions — open it days later with research_project_continue and you get every prior finding, hypothesis, and open gap. Depth controls how aggressively the synthesizer explores: overview (5 docs), standard (10 docs), deep (20+ docs with adversarial verification).', inputSchema: { type: 'object', properties: { userId: { type: 'string', description: 'Owner user_id (matches memory userId).' }, name: { type: 'string', description: 'Short project label.' }, question: { type: 'string', description: 'The central question to investigate.' }, depth: { type: 'string', description: '"overview" | "standard" | "deep". Default "standard".' }, }, required: ['name', 'question'], }, }, handler: handleProjectCreate, }, - packages/core/src/mcp/dispatcher.ts:39-46 (registration)buildRegistry() combines RESEARCH_TOOLS (among others) into the full registry. This is where RESEARCH_TOOLS is imported and included.
export function buildRegistry(): RegisteredTool[] { return [ ...OPENCORE_TOOLS, ...JOURNAL_TOOLS, ...WRITE_TOOLS, ...RESEARCH_TOOLS, ]; } - ensureSchema helper that lazily creates the research_projects (and related) tables on first call. Called by handleProjectCreate before inserting a new project.
let schemaReady = false; async function ensureSchema(ctx: McpToolContext): Promise<unknown> { const pool = ctx.pool as { query: (sql: string, params?: any[]) => Promise<any> } | undefined; if (!pool) throw new Error('research tools require pool in McpToolContext'); if (!schemaReady) { await pool.query(RESEARCH_SCHEMA_SQL); schemaReady = true; } return pool; }