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

fork this repository into your github organisation.
edit organisation.md with your team's identity, projects, decisions, and preferences.
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. run in sse mode (for remote agents)

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

the server starts on http://localhost:3000/sse. configure your remote mcp host to connect to this endpoint.

4. 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

configuration

copy .env.example to .env and fill in your values:

cp .env.example .env

variable	required	default	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 (e.g., `organisation.md`)
`TRANSPORT`	no	`stdio`	transport mode — `stdio` for local mcp hosts, `sse` for remote connections
`PORT`	no	`3000`	port for sse transport (only used when `TRANSPORT=sse`)

customisation

edit organisation.md — replace the template content with your team's actual identity, projects, and decisions.
add context/ files — create additional markdown files for deeper context (architecture docs, runbooks, etc.).
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.