organisation.md

your team's living memory — an mcp server backed by a git repo.

organisation.md turns any github repository into your organisation's persistent context layer. any mcp-compatible ai tool (claude code, cursor, etc.) can read, search, and propose updates to your team's shared context — without a database, without a hosted service, without leaving your github account.

---

how it works

1. fork this repository into your github organisation.
2. edit organisation.md with your team's identity, projects, decisions, and preferences.
3. run the mcp server — your ai agents connect and read/write context naturally.

all changes go through pull requests — your team reviews and merges them. git provides version history, branching, and access control out of the box.

quickstart

1. generate a personal access token

go to github.com/settings/tokens and generate a classic token with the repo scope. copy the token — you'll need it in the next step.

2. run with npx (recommended)

export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your-github-username-or-org
export GITHUB_REPO=organisation.md
npx @shashank-sn/organisation-md

that's it. the mcp server starts in stdio mode and your ai agent can connect.

3. or clone and run locally

git clone https://github.com/your-org/organisation.md.git
cd organisation.md
npm install
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your-github-username-or-org
export GITHUB_REPO=organisation.md
npx tsx src/server.ts

4. connect to your ai agent

the server speaks mcp over stdio. configure your ai tool to launch it:

claude code — add to your .mcp.json:

{
  "mcpServers": {
    "organisation.md": {
      "command": "npx",
      "args": ["@shashank-sn/organisation-md"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GITHUB_OWNER": "your-org",
        "GITHUB_REPO": "organisation.md"
      }
    }
  }
}

cursor / continue / other mcp hosts — point to the same command with env vars.

tools

tool	description
read_org	read the full organisation.md file from the github repo
read_section	read a specific section by heading (e.g., "team", "decisions")
update_section	propose an update to a section — creates a pull request
search_context	search across organisation.md and all context/ files
propose_change	propose a change to any file in the repo — creates a pull request
list_context_files	list all files in the context/ directory
import_file	import a txt, md, or docx file into the knowledge base
add_info	add information via natural language — auto-detects the section
remove_info	remove information matching a description
check_roles	check git-based roles and codeowners
check_permissions	check if you can add/delete/approve/merge
configure_codeowners	update .github/codeowners for team access control
report_bug	auto-detect the area and file a github issue
suggest_feature	suggest a feature or improvement as a github issue

repository structure

organisation.md/
├── organisation.md          # canonical org context file
├── context/                 # supporting context files
│   ├── README.md
│   ├── projects.md          # detailed project info
│   ├── architecture.md      # system architecture
│   └── people.md            # team members and roles
├── src/                     # mcp server source (typescript)
│   ├── server.ts            # entry point
│   ├── github/              # octokit wrapper (files, git api)
│   ├── content/             # markdown parser and template
│   ├── tools/               # mcp tool implementations
│   └── resources/           # mcp resource templates
├── docs/                    # documentation
│   ├── quickstart.md        # full setup guide
│   ├── agent-prompt.md      # prompt template for ai agents
│   └── example-flows.md     # common workflows
├── scripts/
│   └── build-site.mjs       # github pages build script
├── .github/workflows/
│   ├── ci.yml               # ci: typecheck + test on push/pr
│   └── pages.yml            # github pages deployment
├── strategy.md              # product strategy
├── license                  # mit
└── README.md

environment variables

variable	required	description
github_token	yes	github personal access token with repo scope
github_owner	yes	github username or organisation that owns the repo
github_repo	yes	repository name (defaults to organisation.md)

customisation

1. edit organisation.md — replace the template content with your team's actual identity, projects, and decisions.
2. add context/ files — create additional markdown files for deeper context (architecture docs, runbooks, etc.).
3. fork and rename — fork the repo into your org and update the env vars to point at your fork.

development

npm install
npm run dev         # development server with hot reload
npm test            # run tests
npm run typecheck   # typescript checking
npm run build       # compile typescript
npm run build:site  # build github pages site locally

license

mit — fork it, use it, ship it. see license.