Skip to main content
Glama
Sign In
organisation.md

organisation.md

by shashank-sn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

organisation.md

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

MIT License CI

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.

Related MCP server: git-context-mcp

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

  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.

Available Tools

12 tools
add_infoA

add information to the knowledge base using natural language. describes what to add, and the tool figures out which section and file to put it in.

Inputs: info (required), source, section.

check_permissionsA
Read-only

check if the current user can perform a specific action (add, delete, approve, merge).

Inputs: action (required), path.

check_rolesA
Read-only

check who has what permissions on this repo. reads the codeowners file and current collaborator permissions.

Inputs: user.

configure_codeownersB

update the .github/codeowners file to define who can approve changes to specific paths.

Inputs: pattern (required), owners (required), message.

import_fileA

import a file (txt, md, docx) into the repo as context. creates a context/ entry and updates the organisation.md index. the ai agent passes file content it has already read.

Inputs: fileName (required), content (required), fileType (required), section, +1 more.

list_context_filesB
Read-only

List all files in the CONTEXT/ directory of the repo.

Inputs: no named parameters.

propose_changeB

Propose a change to any file in the organisation.md repo. Creates a pull request.

Inputs: path (required), content (required), message (required).

read_orgA
Read-only

Read the full organisation.md file from the GitHub repo.

Inputs: no named parameters.

read_sectionA
Read-only

Read a specific section from organisation.md by heading name.

Inputs: section (required).

remove_infoB

remove information from the knowledge base using natural language. describes what to remove, and the tool finds and removes it.

Inputs: query (required), section.

search_contextA
Read-only

Search across organisation.md and CONTEXT/ files for matching text.

Inputs: query (required).

update_sectionB

Propose an update to a section in organisation.md. Creates a pull request for review.

Inputs: section (required), content (required), message (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: reading (read_org, read_section), writing via PR (update_section, propose_change), natural language modifications (add_info, remove_info), permissions (check_permissions, check_roles, configure_codeowners), and file management (import_file, list_context_files, search_context). No two tools overlap in functionality.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern in snake_case (e.g., add_info, list_context_files, update_section). All names are clear and predictable, with no mixing of conventions.

    Tool Count5/5

    With 12 tools, the server is well-scoped for its purpose of managing an organisation.md knowledge base and associated context files. Each tool addresses a specific operation, neither too few nor too many.

    Completeness4/5

    The tool set covers reading, updating, adding/removing information, searching, importing files, and permissions. Minor gaps include no tool to delete a context file directly (only import and list) and no direct write without PR, but these are reasonable for a review-based workflow.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers