context1000

context1000 is a documentation format for software systems, designed for integration with artificial intelligence tools. The key artifacts are ADRs and RFCs, enriched with formalized links between documents.

This project demonstrates an implementation of a context portal and consists of two parts:

1. Documentation format (@context1000/docs)
2. Simple RAG (Retrieval Augmented Generation) for this format with the ability to run locally.

Getting started

Install

Install context1000 package globally:

npm i context1000 -g

Set up environment

In the project where you use agents, create a .env file in the root directory of the project.

touch .env
echo "CHROMA_URL=http://localhost:8000" >> .env
echo "OPENAI_API_KEY=your-key" >> .env

Start ChromaDB

docker run -p 8000:8000 chromadb/chroma

Prepare documentation

Start with special docs template: https://github.com/context1000/templates. Or grab a raw template from https://github.com/context1000/docs.

Index your documentation

It will be vectorized and stored documentation content in ChromaDB.

npx context1000 index /path/to/docs

Use your documentation with MCP

Claude Code

Local server connection (stdio transport)

claude mcp add context1000 \
  -e OPENAI_API_KEY=your-key \
  -e CHROMA_URL=http://localhost:8000 \
  -- npx context1000 mcp

Remote server connection (HTTP/SSE transport)

Note: dont forget about env variables OPENAI_API_KEY and OPENAI_API_KEY

Start the MCP server with HTTP or SSE transport:

# Start server on default port 3000 with HTTP transport
npx context1000 mcp --transport http

# Start server with SSE transport
npx context1000 mcp --transport sse

# Or specify a custom port
npx context1000 mcp --transport http --port 3001
npx context1000 mcp --transport sse --port 3001

Then add it to Claude Code:

# Using HTTP transport (default port)
claude mcp add --transport http context1000 http://localhost:3000/mcp

# Using SSE transport
claude mcp add --transport sse context1000 http://localhost:3000/sse

# Using custom port
claude mcp add --transport http context1000 http://localhost:3001/mcp
claude mcp add --transport sse context1000 http://localhost:3001/sse

# For remote servers (replace with your server's URL)
claude mcp add --transport http context1000 https://myhost:3000/mcp
claude mcp add --transport sse context1000 https://myhost:3000/sse