Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.mdwith 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-mdthat'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.ts4. 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.mdenvironment 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
- 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 locallylicense
mit — fork it, use it, ship it. see license.