Skip to content

Commit ea2aaba

Browse files
shtse8shtse8
committed
docs: adopt doctrine project manifest
1 parent 2022252 commit ea2aaba

3 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎.doctrine/project.json‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
{
2+
"schemaVersion": 1,
3+
"project": {
4+
"repo": "SylphxAI/filesystem-mcp",
5+
"name": "Filesystem MCP",
6+
"lifecycle": "production",
7+
"layer": "tooling",
8+
"summary": "Filesystem MCP is a production MCP server that provides secure, token-efficient, project-root-confined filesystem tools for AI agents.",
9+
"goals": [
10+
"Own the filesystem MCP server, tool schemas, path-safety model, batch operations, docs, package, Docker image, and release workflows.",
11+
"Keep filesystem side effects explicit, validated, root-confined, and safe for autonomous agents.",
12+
"Publish artifacts only with CI, release intent, npm/Docker readback, and GitHub release evidence."
13+
],
14+
"nonGoals": [
15+
"Own downstream agent policy, host configuration, or project-specific filesystem rules.",
16+
"Bypass root confinement or make shell execution a hidden filesystem transport.",
17+
"Treat source revert as complete recovery after npm or Docker publish."
18+
]
19+
},
20+
"boundaries": {
21+
"owns": [
22+
{
23+
"name": "mcp-filesystem-tools",
24+
"description": "MCP tool schemas and implementations for root-confined read, write, edit, search, copy, move, delete, chmod, and chown operations."
25+
},
26+
{
27+
"name": "filesystem-mcp-release-artifacts",
28+
"description": "npm package, Docker image, generated docs, and release workflows for Filesystem MCP."
29+
}
30+
],
31+
"doesNotOwn": [
32+
"Downstream agent policy, host configuration, or project-specific filesystem rules.",
33+
"Enterprise doctrine, org-wide branch protection, or external MCP host behavior.",
34+
"The npm registry, Docker Hub, GitHub release infrastructure, or Codecov."
35+
],
36+
"publicSurfaces": [
37+
{
38+
"type": "package-export",
39+
"name": "@sylphx/filesystem-mcp npm package and CLI",
40+
"location": "package.json"
41+
},
42+
{
43+
"type": "api",
44+
"name": "MCP filesystem tools",
45+
"location": "README.md"
46+
},
47+
{
48+
"type": "workflow",
49+
"name": "CI, publish, and release workflow",
50+
"location": ".github/workflows/publish.yml"
51+
},
52+
{
53+
"type": "status-context",
54+
"name": "Required branch contexts",
55+
"location": "Validate Code Quality, Build and Archive Artifacts, Publish to NPM, Publish to Docker Hub, Create GitHub Release"
56+
}
57+
],
58+
"allowedDependencies": [
59+
{
60+
"repo": "SylphxAI/doctrine",
61+
"surface": "enterprise engineering doctrine",
62+
"direction": "downward"
63+
},
64+
{
65+
"repo": "SylphxAI/.github",
66+
"surface": "reusable release workflow",
67+
"direction": "downward"
68+
}
69+
],
70+
"forbiddenCouplings": [
71+
"Do not add host-specific filesystem behavior without a documented MCP option or public contract.",
72+
"Do not weaken root confinement, path traversal prevention, or side-effect validation for convenience.",
73+
"Do not rely on source revert for already-published npm or Docker artifacts."
74+
]
75+
},
76+
"documentation": {
77+
"adr": {
78+
"path": "docs/adr/",
79+
"status": "planned"
80+
},
81+
"specs": {
82+
"path": "README.md",
83+
"status": "present"
84+
},
85+
"catalog": {
86+
"path": "PROJECT.md",
87+
"status": "present"
88+
},
89+
"runbooks": {
90+
"path": ".github/workflows/publish.yml",
91+
"status": "present"
92+
},
93+
"generatedReferences": {
94+
"path": "docs/",
95+
"status": "generated"
96+
}
97+
},
98+
"delivery": {
99+
"ciModel": "legacy-ci",
100+
"requiredContexts": [
101+
"Build and Archive Artifacts",
102+
"Create GitHub Release",
103+
"Publish to Docker Hub",
104+
"Publish to NPM",
105+
"Validate Code Quality"
106+
],
107+
"deployPath": "Publish workflow validates on PR/merge-group and publishes npm, Docker Hub, GitHub Release, and docs artifacts on tag/main release paths.",
108+
"productionProof": "Required contexts, package build output, npm readback, Docker image readback, GitHub release evidence, docs build evidence, and MCP smoke tests.",
109+
"recoveryClass": "forward-fix-only",
110+
"packageRelease": {
111+
"publishesPackages": true,
112+
"ecosystems": [
113+
"npm",
114+
"docker-hub",
115+
"github-release",
116+
"changesets"
117+
],
118+
"releaseIntent": "Changesets and version tags capture package/image release intent.",
119+
"versionPr": "Changesets version changes and release workflow evidence must precede publish.",
120+
"publisher": "GitHub Actions publish workflow with NPM_TOKEN and Docker Hub credentials.",
121+
"requiredContexts": [
122+
"Validate Code Quality"
123+
],
124+
"publishProof": "npm package readback, Docker Hub image tags, GitHub Release, and attached build artifact."
125+
}
126+
},
127+
"adoption": {
128+
"status": "baseline",
129+
"gaps": [
130+
{
131+
"id": "central-admission",
132+
"description": "CI is repo-local legacy GitHub Actions; migrate to central admission or stable status fan-in when the fleet workflow is ready.",
133+
"owner": "SylphxAI/filesystem-mcp",
134+
"target": "before full doctrine adoption"
135+
},
136+
{
137+
"id": "release-context-scope",
138+
"description": "Branch protection requires tag/publish context names; verify skipped release-only contexts are intentional for PR and merge-group flows.",
139+
"owner": "SylphxAI/filesystem-mcp",
140+
"target": "before claiming full package-release adoption"
141+
}
142+
]
143+
}
144+
}

‎AGENTS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Agent Instructions
2+
3+
Engineering doctrine: https://github.com/SylphxAI/doctrine
4+
5+
Before changing behavior, read `PROJECT.md`, `.doctrine/project.json`, the
6+
central doctrine entry points, and triggered doctrine standards. This file is a
7+
thin runtime adapter; keep enterprise policy in doctrine.
8+
9+
## Local Commands
10+
11+
- `pnpm install --frozen-lockfile` - install dependencies.
12+
- `pnpm run validate` - formatting, lint, typecheck, and tests.
13+
- `pnpm run build` - build package artifacts.
14+
- `pnpm run docs:build` - build documentation.
15+
16+
## Local Hazards
17+
18+
- This is a security-sensitive MCP filesystem server. Path confinement, batch
19+
write/edit behavior, chmod/chown, and delete/copy/move tools are public safety
20+
contracts.
21+
- Release workflows publish npm, Docker Hub images, GitHub releases, and docs.
22+
Published artifacts are forward-fix-only.
23+
- Do not mix package/image publishing changes with docs/control-plane changes.
24+
25+
## Reporting
26+
27+
Separate local diff, PR state, CI state, merge state, package/image release
28+
state, and runtime/MCP proof.

‎PROJECT.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Filesystem MCP Project
2+
3+
Filesystem MCP is a production MCP server that gives AI agents secure,
4+
token-efficient filesystem tools with project-root confinement and batch
5+
operations. It publishes npm and Docker artifacts for MCP hosts.
6+
7+
## Goals
8+
9+
- Own the filesystem MCP server, tool schemas, path-safety model, batch
10+
operations, docs, package, Docker image, and release workflows.
11+
- Keep filesystem side effects explicit, validated, root-confined, and safe for
12+
autonomous agents.
13+
- Publish artifacts only with CI, release intent, npm/Docker readback, and
14+
GitHub release evidence.
15+
16+
## Non-Goals
17+
18+
- Do not own downstream agent policy, host configuration, or project-specific
19+
filesystem rules.
20+
- Do not bypass root confinement or make shell execution a hidden filesystem
21+
transport.
22+
- Do not treat source revert as complete recovery after npm or Docker publish.
23+
24+
## Boundaries
25+
26+
Owned contexts are MCP tool APIs, filesystem operation semantics, root
27+
confinement, validation schemas, docs, npm package, Docker image, and release
28+
workflows.
29+
30+
Public surfaces:
31+
32+
- npm package and CLI in `package.json`.
33+
- MCP tools documented in `README.md`.
34+
- Docker image `sylphx/filesystem-mcp`.
35+
- Required contexts `Validate Code Quality`, `Build and Archive Artifacts`,
36+
`Publish to NPM`, `Publish to Docker Hub`, and `Create GitHub Release`.
37+
38+
## Delivery
39+
40+
Current CI model: `legacy-ci`. Release path is `.github/workflows/publish.yml`
41+
and the central reusable release workflow in `.github/workflows/release.yml`.
42+
Production proof must include required contexts, package build output, npm
43+
readback, Docker image readback, GitHub release evidence, and MCP smoke tests.
44+
45+
Recovery class: `forward-fix-only`, because published npm/Docker versions and
46+
consumer MCP behavior cannot be fully undone by source revert.
47+
48+
## References
49+
50+
- Machine manifest: `.doctrine/project.json`
51+
- Public docs: `README.md`
52+
- Package: `package.json`
53+
- CI/publish: `.github/workflows/publish.yml`
54+
- Release: `.github/workflows/release.yml`
55+
- Doctrine: https://github.com/SylphxAI/doctrine

0 commit comments

Comments
 (0)