Workspace tool (createProject)

Tool names: createProject

Scopes: knowledge:read, knowledge:write

When to use

In the Sasha web interface, the documents of a knowledge project show in the sidebar only inside a workspace with the same name: the person opens the workspace, and its Knowledge section lists the documents. A project that you fill only with writeDoc has no workspace, so nobody can see its documents in the sidebar. createProject creates the workspace, or confirms that it already exists.

Call it before or after writeDoc when you put documents in a project that may have no workspace. It is safe to call every time: an existing workspace returns created: false and is not changed. Documents already in the knowledge project stay as they are. Browsers that are open show the new workspace at once.

The tool is in the tool list only when all of these are true:

The connection holds knowledge:read and knowledge:write.
The person who connected is an admin or staff user. A member connection never gets the tool, because members do not use Sasha chat. The tool is absent, not refused.

Sasha's own chat in the web interface does not have this tool. A person there makes a workspace from the sidebar.

createProject takes:

name: the project id, for example transcriptions. Use the id of the project from listProjects. The name is cleaned as the web interface cleans a new project name: lower case, and any character that is not a letter, digit, - or _ becomes -. Board Notes becomes board-notes.
displayName (optional): the name the sidebar shows, for example Transcriptions. It is used only when the workspace is created. The default is name as you sent it.
folderId (optional): the id of a sidebar folder for a new workspace. It is ignored when the workspace already exists.

An unknown argument is refused.

It returns created (true when this call made the workspace) and project: id and name (the cleaned name, the same value), displayName, and folderId (null when the workspace is in no folder).

When listProjects is called on a connection that may use createProject, each project has hasWorkspace. A project with hasWorkspace: false is one this tool can fix.

Example

An admin makes sure the transcriptions project has a workspace:

{
  "name": "transcriptions",
  "displayName": "Transcriptions"
}

{
  "created": true,
  "project": {
    "id": "transcriptions",
    "name": "transcriptions",
    "displayName": "Transcriptions",
    "folderId": null
  }
}

The same request again returns "created": false with the same project.

Refusals and what to do

A refusal is an error result with the text Error in createProject: <reason>.

forbidden:name_reserved: the name belongs to a member home, a private chats project, or a project that was deleted. Use another name.
invalid_input:name_invalid: the name has no letter or digit. Send a name with at least one.
not_found:folder_not_found: no sidebar folder has that folderId. Send the request again without folderId.
repository_busy:knowledge_lock_busy: another change to the knowledge base is running. Try again in a few seconds.
invalid_input:arguments_invalid (<fields>): the arguments do not match the schema, for example an unknown field.
If the tool is not in your tool list, a call returns MCP error -32602: Tool createProject not found. The connection does not hold knowledge:write, or the person is a member. Read the workspaces and permissions sections of getDocs. Do not tell the person that Sasha cannot do this: an admin or staff user can make the workspace in the web interface.

listProjects lists the projects and, for this connection, hasWorkspace.
writeDoc creates the documents in the project.
getDocs has the workspaces and permissions sections.

Workspace tool (createProject)

When to use

Example

Refusals and what to do

Related