Skip to content

Ecosystem Overview

This tutorial walks through installing the full projio ecosystem, initializing a workspace, connecting the MCP server, and verifying that all tools are available.

By the end you will have a working project with semantic search, bibliography management, structured notes, and code intelligence — all accessible to AI agents via MCP.

Platform support

Platform Support level Notes
Linux Full Primary development platform
macOS Full Requires Xcode CLI tools for make (xcode-select --install)
Windows (WSL) Full Recommended for Windows users — everything works inside WSL
Windows (native) Core MCP server, search, bibliography, notes, code intelligence, docs, manuscript all work. Pipeline execution (pipeio run) and DataLad require WSL. Git hooks are skipped.

For Windows native, install with pip directly (no make needed):

pip install "projio[all]"

Prerequisites

  • Python 3.11+
  • A git repository (or a new empty directory)
  • Claude Code or Claude Desktop for the MCP agent interface

Step 1: Install the ecosystem

Install projio with all ecosystem packages:

pip install "projio[all]"

This pulls in:

Package PyPI name Domain
projio projio Orchestrator + MCP server
indexio indexio Semantic search / RAG
biblio biblio-tools Bibliography management
notio notio Structured notes
codio codio-tools Code intelligence
pipeio pipeio Pipeline registry + notebook lifecycle
figio figio-tools Declarative figure orchestration

To install individual components:

pip install projio           # core only
pip install "projio[biblio]" # core + bibliography
pip install "projio[indexio,notio]" # core + search + notes
pip install pipeio           # pipeline management (separate package)

Step 2: Initialize the workspace

From your project root:

projio init .

This creates:

  • .projio/config.yml — project configuration
  • .projio/projio.mk — Makefile include with shortcuts
  • Makefile — project Makefile (if none exists)
  • .gitignore — with managed projio section
  • docs/index.md — documentation landing page
  • mkdocs.yml — site configuration (if no framework detected)

For a Python package project, use:

projio init . --kind tool

For a lightweight study/analysis project:

projio init . --kind study

Step 3: Activate subsystems

Use projio init with the -c flag to activate components in one step:

projio init -c full    # activates notio, biblio, codio, indexio, pipeio

Or activate individually:

projio add notio
projio add biblio
projio add codio
projio add indexio
projio add pipeio
projio add claude      # set up Claude Code permissions + CLAUDE.md

After initialization, all components live under .projio/:

your-project/
├── .projio/
│   ├── config.yml         # projio config
│   ├── packages.yml       # enabled packages
│   ├── projio.mk          # Makefile include
│   ├── notio/             # note templates
│   ├── biblio/            # bibliography marker
│   ├── codio/             # catalog.yml + profiles.yml
│   │   ├── catalog.yml
│   │   └── profiles.yml
│   ├── indexio/           # search config + index
│   │   └── config.yaml
│   ├── pipeio/            # pipeline registry
│   │   └── registry.yml
│   └── skills/            # project-level skills (optional)
├── bib/                   # biblio workspace (visible)
│   ├── main.bib
│   └── config/
├── notes/                 # notio notes
└── docs/

Step 4: Connect the MCP server

Generate the MCP configuration automatically:

projio mcp-config -C .          # preview
projio mcp-config -C . --yes    # write .mcp.json

This writes a .mcp.json that Claude Code picks up on next launch:

{
  "mcpServers": {
    "projio": {
      "command": "/path/to/python",
      "args": ["-m", "projio.mcp.server"],
      "env": { "PROJIO_ROOT": "/path/to/your/project" }
    }
  }
}

If your projio ecosystem lives in a specific conda/venv environment, set the binary path in your user config:

# ~/.config/projio/config.yml
runtime:
  python_bin: /path/to/envs/projio/bin/python

Step 5: Configure agent permissions

Set up Claude Code to auto-approve projio MCP tools:

projio add claude

This creates .claude/settings.json with mcp__projio__* in the allowed tools list, so the agent can call any projio tool without prompting. The MCP server is already scoped to your project via PROJIO_ROOT, so all writes stay within the repo.

For details on the security model and granular permission options, see Agent Safety & Permissions.

Step 6: Verify tools are available

Start Claude Code in your project directory. The MCP servers panel should show projio as connected.

Ask the agent to list available tools:

You: Call project_context to see the project metadata.

The agent calls project_context() and returns your project name, README excerpt, config, and key paths.

Verify each subsystem

Semantic search: 

You: List the indexed corpora.
Agent calls corpus_list() — returns available corpora with chunk counts.

Bibliography: 

You: What note types are configured?
Agent calls note_types() — lists all configured types and their modes.

Code intelligence: 

You: Show the codio vocabulary.
Agent calls codio_vocab() — returns the controlled vocabulary for registry fields.

Notes: 

You: List recent notes.
Agent calls note_list() — returns the most recent notes across all types.

Step 7: Check project status

From the command line:

projio status -C .

This reports which ecosystem components are detected and their configuration state.

To print clickable URLs for your repo and documentation:

projio url -C .

What each subsystem provides

Build a searchable corpus from your project's documents, code, and papers:

indexio build          # chunk and embed registered sources

Then query via MCP: rag_query("travelling wave methods") returns ranked passages with source attribution.

biblio — Bibliography

Manage papers as structured data:

  • Ingest by DOI via OpenAlex
  • Generate BibTeX entries with deterministic citekeys
  • Extract full text with docling
  • Parse references with GROBID
  • Track reading status and tags in a library ledger

notio — Structured notes

Create templated markdown notes with frontmatter:

notio note meeting --title "Sprint sync"
notio note idea --title "New analysis approach"
notio toc --all    # rebuild indexes

Note types: daily, weekly, meeting, idea, issue, task, commit, personal — all configurable.

codio — Code intelligence

Maintain a registry of libraries with structured metadata:

  • Catalog (identity) + Profile (project-local policy)
  • Controlled vocabulary for fields
  • Capability search across registered libraries
  • Bulk-add from GitHub/GitLab URLs

pipeio — Pipeline management

Manage computational pipelines in a pipe / flow / mod hierarchy:

pipeio registry scan    # discover flows from filesystem
pipeio registry validate  # check registry consistency
pipeio flow list        # list all flows

Query via MCP: pipeio_flow_list() returns the registry, pipeio_mod_list(pipe, flow) returns mods within a flow, pipeio_mod_resolve(modkeys) resolves modkey strings.

Skills — Agent workflow guidance

Projio ships ecosystem-level skills that guide agents through common workflows:

Skill Purpose
idea-capture Capture analysis idea as structured note
codelib-discovery Search code corpora for existing implementations
literature-discovery Search paper corpus for methods and parameters
rag-query Query code / docs / papers via RAG

Skills are discovered automatically by agent_instructions(). Projects can add their own skills in .projio/skills/ — these override ecosystem skills by name.

Next steps