projects.register
Register a project with Kontexta to index its markdown files, persist metadata, and link declared tools.
Instructions
Register a new project and link it to the Kontexta knowledge system.
SIDE EFFECTS: Writes project metadata to disk (persisted in the Kontexta data directory). Scans the project root recursively to discover and index all markdown files into the local database. Registers any kontexta.json-declared Hands tools found in the project root. This operation is idempotent — re-registering an existing project updates its metadata without data loss.
AUTH / RATE LIMITS: None. Operates entirely on the local file system.
PARAMETERS:
name: Human-readable project name.
path: Absolute path to the project root. Required. DO NOT guess or assume the path based on the active editor workspace unless the user explicitly asks to register the "current" or "open" project. If the user provides a project name but no path, ask them for the absolute path before calling this tool. Fails with a descriptive error if the path does not exist or is inaccessible.
description: Optional free-text description stored with the project metadata.
RETURNS: A JSON object containing:
project: { id, name, path, description, created_at }
discovered_files_count: number of markdown files indexed
discovered_files: array of { path, est_tokens, size_bytes } for each file
total_est_tokens: estimated total token cost of all discovered files
hands: { found, tools_registered, tools_disabled, warnings }
warnings: array of non-fatal issues (e.g. scan failures, token budget exceeded)
ERROR CONDITIONS: Returns isError=true if path is missing or unresolvable. Scan failures are non-fatal and reported in warnings rather than as errors.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name | |
| path | Yes | Absolute path to the project root. Required. DO NOT guess from the active workspace unless asked. Ask the user if unsure. | |
| description | No | Optional project description |