@projitive/mcp 1.0.6 → 1.0.8

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.6**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.8**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -177,7 +177,7 @@ npm run test
 #### `projectNext`
 
 - **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).
-- **Input**: `maxDepth?`, `limit?`
+- **Input**: `limit?`
 - **Output Example (Markdown)**:
 
 ```markdown
@@ -294,7 +294,7 @@ npm run test
 #### `taskNext`
 
 - **Purpose**: one-step workflow for project discovery + best task selection + evidence/read-order output.
-- **Input**: `maxDepth?`, `topCandidates?`
+- **Input**: `limit?`
 - **Output Example (Markdown)**:
 
 ```markdown

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "1.0.6",
+    "version": "1.0.8",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",

package/output/source/projitive.js

@@ -133,6 +133,41 @@ function parentDir(dirPath) {
     const parent = path.dirname(dirPath);
     return parent === dirPath ? null : parent;
 }
+export function toProjectPath(governanceDir) {
+    return path.dirname(governanceDir);
+}
+async function listChildGovernanceDirs(parentPath) {
+    const entriesResult = await catchIt(fs.readdir(parentPath, { withFileTypes: true }));
+    if (entriesResult.isError()) {
+        return [];
+    }
+    const folders = entriesResult.value
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(parentPath, entry.name));
+    const markerChecks = await Promise.all(folders.map(async (folderPath) => ({
+        folderPath,
+        hasMarker: await hasProjectMarker(folderPath),
+    })));
+    const candidates = markerChecks
+        .filter((item) => item.hasMarker)
+        .map((item) => item.folderPath)
+        .sort((a, b) => a.localeCompare(b));
+    return candidates;
+}
+async function resolveChildGovernanceDir(parentPath) {
+    const candidates = await listChildGovernanceDirs(parentPath);
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const defaultCandidate = path.join(parentPath, DEFAULT_GOVERNANCE_DIR);
+    if (candidates.includes(defaultCandidate)) {
+        return defaultCandidate;
+    }
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    throw new Error(`Multiple governance roots found under path: ${parentPath}. Use projectPath/governanceDir explicitly.`);
+}
 export async function resolveGovernanceDir(inputPath) {
     const absolutePath = path.resolve(inputPath);
     const statResult = await catchIt(fs.stat(absolutePath));
@@ -145,6 +180,10 @@ export async function resolveGovernanceDir(inputPath) {
         if (await hasProjectMarker(cursor)) {
             return cursor;
         }
+        const childGovernanceDir = await resolveChildGovernanceDir(cursor);
+        if (childGovernanceDir) {
+            return childGovernanceDir;
+        }
         cursor = parentDir(cursor);
     }
     throw new Error(`No ${PROJECT_MARKER} marker found from path: ${absolutePath}`);
@@ -158,6 +197,8 @@ export async function discoverProjects(rootPath, maxDepth) {
         if (await hasProjectMarker(currentPath)) {
             results.push(currentPath);
         }
+        const childGovernanceDirs = await listChildGovernanceDirs(currentPath);
+        results.push(...childGovernanceDirs);
         const entriesResult = await catchIt(fs.readdir(currentPath, { withFileTypes: true }));
         if (entriesResult.isError()) {
             return;
@@ -274,7 +315,7 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
 export function registerProjectTools(server) {
     server.registerTool("projectInit", {
         title: "Project Init",
-        description: "Bootstrap governance files when a project has no .projitive yet",
+        description: "Bootstrap governance files when a project has no .projitive yet (requires projectPath)",
         inputSchema: {
             projectPath: z.string(),
             governanceDir: z.string().optional(),
@@ -313,7 +354,7 @@ export function registerProjectTools(server) {
                     "- After init, fill owner/roadmapRefs/links in tasks.md before marking DONE.",
                     "- Keep task source-of-truth inside marker block only.",
                 ]),
-                nextCallSection(`projectContext(projectPath=\"${initialized.governanceDir}\")`),
+                nextCallSection(`projectContext(projectPath=\"${initialized.projectPath}\")`),
             ],
         });
         return asText(markdown);
@@ -356,12 +397,11 @@ export function registerProjectTools(server) {
         title: "Project Next",
         description: "Rank actionable projects and return the best execution target",
         inputSchema: {
-            maxDepth: z.number().int().min(0).max(8).optional(),
             limit: z.number().int().min(1).max(50).optional(),
         },
-    }, async ({ maxDepth, limit }) => {
+    }, async ({ limit }) => {
         const root = resolveScanRoot();
-        const depth = resolveScanDepth(maxDepth);
+        const depth = resolveScanDepth();
         const projects = await discoverProjects(root, depth);
         const snapshots = await Promise.all(projects.map(async (governanceDir) => {
             const snapshot = await readTasksSnapshot(governanceDir);
@@ -408,13 +448,13 @@ export function registerProjectTools(server) {
                     ...ranked.map((item, index) => `${index + 1}. ${item.governanceDir} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt} | tasksPath=${item.tasksPath}${item.tasksExists ? "" : " (missing)"}`),
                 ]),
                 guidanceSection([
-                    "- Pick top 1 project and call `projectContext` with its governanceDir.",
+                    "- Pick top 1 project and call `projectContext` with its projectPath.",
                     "- Then call `taskList` and `taskContext` to continue execution.",
                     "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
                 ]),
                 lintSection(ranked[0]?.lintSuggestions ?? []),
                 nextCallSection(ranked[0]
-                    ? `projectContext(projectPath=\"${ranked[0].governanceDir}\")`
+                    ? `projectContext(projectPath=\"${toProjectPath(ranked[0].governanceDir)}\")`
                     : undefined),
             ],
         });
@@ -429,18 +469,20 @@ export function registerProjectTools(server) {
     }, async ({ inputPath }) => {
         const resolvedFrom = normalizePath(inputPath);
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
+        const projectPath = toProjectPath(governanceDir);
         const markerPath = path.join(governanceDir, ".projitive");
         const markdown = renderToolResponseMarkdown({
             toolName: "projectLocate",
             sections: [
                 summarySection([
                     `- resolvedFrom: ${resolvedFrom}`,
+                    `- projectPath: ${projectPath}`,
                     `- governanceDir: ${governanceDir}`,
                     `- markerPath: ${markerPath}`,
                 ]),
-                guidanceSection(["- Call `projectContext` with this governanceDir to get task and roadmap summaries."]),
+                guidanceSection(["- Call `projectContext` with this projectPath to get task and roadmap summaries."]),
                 lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
-                nextCallSection(`projectContext(projectPath=\"${governanceDir}\")`),
+                nextCallSection(`projectContext(projectPath=\"${projectPath}\")`),
             ],
         });
         return asText(markdown);
@@ -453,6 +495,7 @@ export function registerProjectTools(server) {
         },
     }, async ({ projectPath }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
+        const normalizedProjectPath = toProjectPath(governanceDir);
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
         const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
         const roadmapIds = await readRoadmapIds(governanceDir);
@@ -468,6 +511,7 @@ export function registerProjectTools(server) {
             toolName: "projectContext",
             sections: [
                 summarySection([
+                    `- projectPath: ${normalizedProjectPath}`,
                     `- governanceDir: ${governanceDir}`,
                     `- tasksFile: ${tasksPath}`,
                     `- roadmapIds: ${roadmapIds.length}`,
@@ -488,7 +532,7 @@ export function registerProjectTools(server) {
                     "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskList(projectPath=\"${governanceDir}\")`),
+                nextCallSection(`taskList(projectPath=\"${normalizedProjectPath}\")`),
             ],
         });
         return asText(markdown);

package/output/source/projitive.test.js

@@ -31,6 +31,24 @@ describe("projitive module", () => {
         const resolved = await resolveGovernanceDir(deepDir);
         expect(resolved).toBe(governanceDir);
     });
+    it("resolves nested default governance dir when input path is project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "repo");
+        const governanceDir = path.join(projectRoot, ".projitive");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const resolved = await resolveGovernanceDir(projectRoot);
+        expect(resolved).toBe(governanceDir);
+    });
+    it("resolves nested custom governance dir when input path is project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "repo");
+        const governanceDir = path.join(projectRoot, "governance");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const resolved = await resolveGovernanceDir(projectRoot);
+        expect(resolved).toBe(governanceDir);
+    });
     it("discovers projects by marker file", async () => {
         const root = await createTempDir();
         const p1 = path.join(root, "a");
@@ -43,6 +61,24 @@ describe("projitive module", () => {
         expect(projects).toContain(p1);
         expect(projects).toContain(p2);
     });
+    it("discovers nested default governance directory under project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "app");
+        const governanceDir = path.join(projectRoot, ".projitive");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const projects = await discoverProjects(root, 3);
+        expect(projects).toContain(governanceDir);
+    });
+    it("discovers nested custom governance directory under project root", async () => {
+        const root = await createTempDir();
+        const projectRoot = path.join(root, "app");
+        const governanceDir = path.join(projectRoot, "governance");
+        await fs.mkdir(governanceDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const projects = await discoverProjects(root, 3);
+        expect(projects).toContain(governanceDir);
+    });
     it("initializes governance structure under default .projitive directory", async () => {
         const root = await createTempDir();
         const initialized = await initializeProjectStructure(root);

package/output/source/roadmap.js

@@ -6,7 +6,7 @@ import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
 import { ROADMAP_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
 import { findTextReferences } from "./helpers/markdown/index.js";
 import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
-import { resolveGovernanceDir } from "./projitive.js";
+import { resolveGovernanceDir, toProjectPath } from "./projitive.js";
 import { loadTasks } from "./tasks.js";
 export const ROADMAP_ID_REGEX = /^ROADMAP-\d{4}$/;
 function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
@@ -99,7 +99,7 @@ export function registerRoadmapTools(server) {
                 guidanceSection(["- Pick one roadmap ID and call `roadmapContext`."]),
                 lintSection(lintSuggestions),
                 nextCallSection(roadmapIds[0]
-                    ? `roadmapContext(projectPath=\"${governanceDir}\", roadmapId=\"${roadmapIds[0]}\")`
+                    ? `roadmapContext(projectPath=\"${toProjectPath(governanceDir)}\", roadmapId=\"${roadmapIds[0]}\")`
                     : undefined),
             ],
         });
@@ -157,7 +157,7 @@ export function registerRoadmapTools(server) {
                     "- Re-run `roadmapContext` after edits to confirm references remain consistent.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`roadmapContext(projectPath=\"${governanceDir}\", roadmapId=\"${roadmapId}\")`),
+                nextCallSection(`roadmapContext(projectPath=\"${toProjectPath(governanceDir)}\", roadmapId=\"${roadmapId}\")`),
             ],
         });
         return asText(markdown);

package/output/source/tasks.js

@@ -7,7 +7,7 @@ import { findTextReferences } from "./helpers/markdown/index.js";
 import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
 import { catchIt } from "./helpers/catch/index.js";
 import { TASK_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
-import { resolveGovernanceDir, resolveScanDepth, resolveScanRoot, discoverProjects } from "./projitive.js";
+import { resolveGovernanceDir, resolveScanDepth, resolveScanRoot, discoverProjects, toProjectPath } from "./projitive.js";
 import { isValidRoadmapId } from "./roadmap.js";
 export const TASKS_START = "<!-- PROJITIVE:TASKS:START -->";
 export const TASKS_END = "<!-- PROJITIVE:TASKS:END -->";
@@ -535,7 +535,7 @@ export function registerTaskTools(server) {
                 guidanceSection(["- Pick one task ID and call `taskContext`."]),
                 lintSection(lintSuggestions),
                 nextCallSection(nextTaskId
-                    ? `taskContext(projectPath=\"${governanceDir}\", taskId=\"${nextTaskId}\")`
+                    ? `taskContext(projectPath=\"${toProjectPath(governanceDir)}\", taskId=\"${nextTaskId}\")`
                     : undefined),
             ],
         });
@@ -545,12 +545,11 @@ export function registerTaskTools(server) {
         title: "Task Next",
         description: "Start here to auto-select the highest-priority actionable task",
         inputSchema: {
-            maxDepth: z.number().int().min(0).max(8).optional(),
-            topCandidates: z.number().int().min(1).max(20).optional(),
+            limit: z.number().int().min(1).max(20).optional(),
         },
-    }, async ({ maxDepth, topCandidates }) => {
+    }, async ({ limit }) => {
         const root = resolveScanRoot();
-        const depth = resolveScanDepth(maxDepth);
+        const depth = resolveScanDepth();
         const projects = await discoverProjects(root, depth);
         const rankedCandidates = rankActionableTaskCandidates(await readActionableTaskCandidates(projects));
         if (rankedCandidates.length === 0) {
@@ -609,7 +608,7 @@ export function registerTaskTools(server) {
                         "- Ensure each new task has stable TASK-xxxx ID and at least one roadmapRefs item.",
                     ]),
                     nextCallSection(preferredProject
-                        ? `projectContext(projectPath=\"${preferredProject.governanceDir}\")`
+                        ? `projectContext(projectPath=\"${toProjectPath(preferredProject.governanceDir)}\")`
                         : "projectScan()"),
                 ],
             });
@@ -624,7 +623,7 @@ export function registerTaskTools(server) {
         const taskLocation = (await findTextReferences(selected.tasksPath, selected.task.id))[0];
         const relatedArtifacts = Array.from(new Set(referenceLocations.map((item) => item.filePath)));
         const suggestedReadOrder = [selected.tasksPath, ...relatedArtifacts.filter((item) => item !== selected.tasksPath)];
-        const candidateLimit = topCandidates ?? 5;
+        const candidateLimit = limit ?? 5;
         const markdown = renderToolResponseMarkdown({
             toolName: "taskNext",
             sections: [
@@ -672,7 +671,7 @@ export function registerTaskTools(server) {
                     "- Re-run `taskContext` for the selectedTaskId after edits to verify evidence consistency.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskContext(projectPath=\"${selected.governanceDir}\", taskId=\"${selected.task.id}\")`),
+                nextCallSection(`taskContext(projectPath=\"${toProjectPath(selected.governanceDir)}\", taskId=\"${selected.task.id}\")`),
             ],
         });
         return asText(markdown);
@@ -696,7 +695,7 @@ export function registerTaskTools(server) {
         const task = tasks.find((item) => item.id === taskId);
         if (!task) {
             return {
-                ...asText(renderErrorMarkdown("taskContext", `Task not found: ${taskId}`, ["run `taskList` to discover available IDs", "retry with an existing task ID"], `taskList(projectPath=\"${governanceDir}\")`)),
+                ...asText(renderErrorMarkdown("taskContext", `Task not found: ${taskId}`, ["run `taskList` to discover available IDs", "retry with an existing task ID"], `taskList(projectPath=\"${toProjectPath(governanceDir)}\")`)),
                 isError: true,
             };
         }
@@ -753,7 +752,7 @@ export function registerTaskTools(server) {
                     "- After editing, re-run `taskContext` to verify references and context consistency.",
                 ]),
                 lintSection(lintSuggestions),
-                nextCallSection(`taskContext(projectPath=\"${governanceDir}\", taskId=\"${task.id}\")`),
+                nextCallSection(`taskContext(projectPath=\"${toProjectPath(governanceDir)}\", taskId=\"${task.id}\")`),
             ],
         });
         return asText(coreMarkdown);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projitive/mcp",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Projitive MCP Server for project and task discovery/update",
   "license": "ISC",
   "author": "",