neuphlo-mcp

A reusable MCP 2.x server for shared Markdown knowledge. It gives people and agents a durable source of truth, canonical search/fetch tools, safe optional writes, resources, connector ingestion, and an MCP Apps dashboard. Neuphlo maintains the project; the exposed tools, views, URIs, environment variables, and content model are vendor-neutral.

What ships out of the box

• Standard collaboration records: Rooms, Work, Pages, decisions, outcomes, and notes.

• Extensible business records: any safe lowercase type works without a code change.

• Canonical search and fetch tools for agent knowledge retrieval.

• open_dashboard and show_knowledge_table MCP Apps views, with useful text/JSON fallbacks.

• create_record, get_record, search_knowledge, build_summary, and repository validation.

• Idempotent normalized event ingestion, with vendor adapters kept outside the knowledge model.

• knowledge://index, knowledge://records/{id}, and knowledge://connectors resources.

• Streamable HTTP using the modern MCP 2026-07-28 protocol era.

The collaboration defaults align with the current neuphlo-web everyday model while remaining ordinary Markdown concepts. A business can add types such as incident, policy, campaign, or customer alongside them.

Related MCP server: md-graph

Quick start

Requires Node.js 22 or newer.

npm install
cp .env.example .env
npm run build
npm test
npm start

The default endpoint is http://localhost:3000/mcp. The landing page is available at http://localhost:3000/.

Configuration

MCP_PORT=3000
MCP_APP_NAME=Documentation
MCP_CONTENT_ROOT=./content
MCP_WRITE_MODE=readonly
MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1],knowledge-mcp
MCP_LOG_IPS=false
MCP_READ_TOKEN=
MCP_WRITE_TOKEN=
MCP_ACCESS_POLICY_PATH=
MCP_REFERENCE_HASH_KEY=

Use readonly until you deliberately want writes at all. The global read/write tokens are wildcard service credentials. Set MCP_ACCESS_POLICY_PATH to enable individual principals with area-specific grants. See area and person access control.

Record format

---
id: work-0001
type: work
area: shared
title: Prepare the launch
status: open
owner: workspace-owner
created: 2026-09-20T00:00:00.000Z
updated: 2026-09-20T00:00:00.000Z
sensitivity: internal
tags: [launch]
room_id: room-0001
---

The Markdown body contains the durable context.

Required fields are id, type, area, title, status, owner, created, and updated. Frontmatter may contain arbitrary business metadata. New records are stored under areas/<area>/<type-directory>/.

Compatibility

The server registers MCP Apps resources using _meta.ui.resourceUri and retains the legacy flat metadata key for compatible hosts. Clients without UI support still receive useful text and structured content. The canonical search/fetch pair follows the company-knowledge convention used by ChatGPT integrations.

neuphlo-web can register this server as an external MCP service, discover its tools/resources, invoke tools, and read resources. Neuphlo's own workspace MCP endpoint remains responsible for authenticated native operations such as reading Rooms or creating Work; this reusable server does not pretend a Markdown directory has those backend permissions.

Development

npm run check
npm test
npm run build
npm run smoke

See CUSTOMIZING.md for extension guidance, docs/access-control.md for granular authorization, docs/privacy.md for identifier protection, and docs/mcp-ui-authoring.md for additional MCP Apps views.