@co-villa/agentnest-tools 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @co-villa/agentnest-tools：MCP 与 CLI
+
+## Agent 必须自动完成的本地开发流程
+
+默认复用用户已授权的 MCP 连接。Agent 不得让用户手动填写平台 URL、AGENTDOCK_TOKEN 或资源令牌：
+
+1. 调用 list_projects 确认目标 projectId，并检查该项目资源。
+2. 本地启动 App 前自动调用 prepare_local_development({ projectId })；本地 stdio MCP 同时传 App 根目录 directory。
+3. 远程 MCP 返回 config 时，由 Agent 自动保存为 App 根目录 .agentdock/development.json，并把 .agentdock/ 加入 .gitignore；stdio 工具自动执行此步骤。不要让用户复制工具响应或创建绑定文件。
+4. 安装平台最新 SDK，App 服务端代码默认使用 createClient()，不填 url/projectId/token。
+5. 自动运行并验证本地 App 能访问数据库、KV 和 OSS。绑定缺失、过期或项目切换时由 Agent 重新调用准备工具；若 MCP 授权失效，仅请用户重新完成项目授权，再自动继续准备。
+
+数据库创建后需等待 ready；SQL 和写入需要 deploy 权限。不要把 .agentdock/development.json 提交、部署或暴露给浏览器，不复制原 MCP OAuth 凭据。开发绑定最长24小时，资源访问配置10分钟由 SDK 自动续期。
+
+推荐通过 OAuth 连接远程 MCP： https://an.co-villa.cn/mcp 。本地 stdio 入口为 agentnest-mcp，通过 AGENTDOCK_URL 与 AGENTDOCK_TOKEN 配置 Agent 的部署身份。
+
+Streamable HTTP 使用 /mcp；旧式 SSE 客户端（如百度搭子的官方配置示例）使用 https://an.co-villa.cn/sse，认证请求头为 Authorization: Bearer <Agent令牌>。千问等入口按其支持的协议选择地址；火山方舟 Remote MCP 使用 /mcp 和 tools.headers.Authorization。每种传输共用权限与工具，旧式 SSE 的每次 POST 验证原授权。控制台可生成账号范围的 read/deploy/manage 令牌；scope manage 可创建和配置项目。支持 OAuth 的客户端仍优先使用浏览器授权，不需要手动令牌。
+
+OAuth 可选择账号范围（包含未来有权访问的项目）或单个项目。账号范围的 manage 授权允许 create_project、update_project、set_project_environment、set_project_scaling 以及资源和部署管理；get_project 可检查配置及环境变量名称。read 和 deploy 不允许创建项目或修改所有者配置。操作按当前项目角色和配额校验，账号密码、用户管理和令牌签发仍需用户完整登录身份。旧授权需重新授权才可获取 manage 权限。
+
+## Agent 开发 Node.js App
+
+Node.js App 默认启用项目资源绑定。开发服务端代码时安装 @co-villa/agentnest-sdk 并使用 createClient()，平台自动注入访问配置；不要让用户手动生成资源令牌，不要将部署令牌作为应用资源令牌。资源需先通过 MCP 创建，数据库轮询到 ready；resources:false 可显式关闭绑定。
+
+用 list_resources 检查项目资源；用 create_database、create_kv_namespace、create_storage_bucket 创建缺失资源，用 get_database 轮询 ready。开发阶段可使用 query_database、get_kv_entry、put_kv_entry、put_storage_object 等工具操作数据。
+
+安装最新 @co-villa/agentnest-sdk 并保留 lockfile，在 App 服务端代码中使用：
+
+```js
+import { createClient } from '@co-villa/agentnest-sdk';
+const app = createClient();
+const config = await app.kv('settings').get('config');
+const { rows } = await app.db.query('SELECT $1::text AS message', ['hello']);
+const files = await app.oss('uploads').list();
+```
+
+通过 deploy_site 或 CLI 部署 Node.js App，无需显式设置 resources:true。resourceScopes 可指定权限子集；需要关闭绑定时使用 resources:false，CLI 使用 --no-resources。等待部署 ready 后检查网站。Node.js 须监听 process.env.PORT 和 0.0.0.0。
+
+App 自动资源令牌与 Agent 部署令牌用途不同，不要混用；不需要给 App 生成手动令牌。纯静态浏览器通过 App 后端访问资源；Worker 显式开启 resources:true 后使用 env.KV、env.DB、env.OSS。
+
+数据库密码与删除数据库/命名空间/桶、域名变更仍要求所有者完整身份；普通项目令牌受项目隔离和配额约束。完整工具说明见平台 /help/mcp 与仓库 docs/AGENT_DEPLOY.md。
+
+## 本地开发自动复用 MCP 授权
+
+用户只需在 Agent 客户端连接 MCP 并授权目标项目，不必设置 AGENTDOCK_URL/AGENTDOCK_TOKEN，也不必生成资源令牌。
+
+Agent 开发本地 App 时，自动调用 `prepare_local_development({ projectId })`。远程 MCP 返回仅限该项目的开发绑定，Agent 自动将 config 写到 App 根目录 `.agentdock/development.json`，并将 `.agentdock/` 加入 .gitignore；不要让用户复制凭据或填写环境变量。本地 stdio MCP 可传 directory，工具会自动完成保存和 git 忽略。
+
+App 中直接使用：
+
+```js
+import { createClient } from '@co-villa/agentnest-sdk';
+const app = createClient();
+const config = await app.kv('settings').get('config');
+const { rows } = await app.db.query('SELECT $1::text AS message', ['hello']);
+const files = await app.oss('uploads').list();
+```
+
+SDK 自动读取本地绑定、换取 10 分钟有效的资源配置，并在过期前续期。开发绑定最长 24 小时，不保存 MCP 原始 OAuth/Agent 令牌；原 MCP 授权被撤销、过期或失去项目权限时立即拒绝资源访问。绑定过期时由 Agent 重新调用准备工具。使用其他项目时由 Agent 重新准备绑定；createClient({ project }) 会校验匹配，不会擅自切换项目。
+
+read 授权仅允许读取 KV/OSS，SQL 与写入需要 deploy 授权。数据库、命名空间和桶必须已创建。本地访问真实项目资源，浏览器通过本地 Node.js 后端访问。绑定文件不提交、不上传，CLI 自动排除 .agentdock 目录。已有环境变量授权方式仅作为兼容路径，不再是默认开发指引。

package/cli/index.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { readFile, readdir, lstat, writeFile } from 'node:fs/promises';
+import { resolve, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+
+export async function collectFiles(directory) {
+  const base = resolve(directory);
+  const files = [];
+  let total = 0;
+  async function walk(folder) {
+    for (const entry of await readdir(folder, { withFileTypes: true })) {
+      if (
+        /^(node_modules|\.git|\.agentdock|\.npmrc|\.ssh|\.aws|\.env(?:\..*)?|\.DS_Store|coverage|test-results)$/i.test(
+          entry.name,
+        ) ||
+        /\.(pem|key|p12|pfx)$/i.test(entry.name)
+      )
+        continue;
+      const full = join(folder, entry.name);
+      if ((await lstat(full)).isSymbolicLink())
+        throw new Error(`不支持符号链接：${relative(base, full)}`);
+      if (entry.isDirectory()) await walk(full);
+      else if (entry.isFile()) {
+        const bytes = await readFile(full);
+        total += bytes.length;
+        if (total > 20 * 1024 * 1024 || files.length >= 2000)
+          throw new Error('部署最大为 20 MiB / 2000 个文件，请选择构建产物目录');
+        files.push({
+          path: relative(base, full).split(sep).join('/'),
+          content: bytes.toString('base64'),
+        });
+      }
+    }
+  }
+  await walk(base);
+  return files.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const command = args.shift() ?? 'help';
+  const flags = {};
+  const positional = [];
+  while (args.length) {
+    const arg = args.shift();
+    if (arg.startsWith('--')) {
+      const name = arg.slice(2);
+      if (['no-wait', 'spa', 'build', 'resources', 'no-resources'].includes(name)) flags[name] = true;
+      else {
+        if (!args[0] || args[0].startsWith('--')) throw new Error(`${arg} 缺少值`);
+        flags[name] = args.shift();
+      }
+    } else positional.push(arg);
+  }
+  if (command === 'help')
+    return {
+      usage: [
+        'agentdock init [directory] --project my-site --kind static|node|worker',
+        'agentdock projects',
+        'agentdock deploy [directory] --project my-site --kind static|node|worker [--spa] [--build] [--no-wait]',
+        'agentdock status <deployment-id>',
+        'agentdock logs <deployment-id>',
+        'agentdock promote <project-id> <deployment-id>',
+        'agentdock env <project-id> --file variables.json',
+      ],
+      authentication:
+        'AGENTDOCK_URL + AGENTDOCK_TOKEN（本地开发自动读取平台 .agentdock/admin-token）',
+      output: 'stdout 始终为 JSON；失败退出码 1。默认等待部署完成，--no-wait 立即返回部署 ID。',
+    };
+  if (command === 'init') {
+    const target = resolve(positional[0] ?? '.');
+    const kind = flags.kind ?? 'static';
+    if (!['static', 'node', 'worker'].includes(kind))
+      throw new Error('kind 必须为 static、node 或 worker');
+    const config = {
+      project: flags.project ?? 'my-site',
+      kind,
+      directory: '.',
+      ...(kind === 'worker' ? { entry: 'worker.js', compatibilityDate: '2026-09-01' } : {}),
+      ...(kind === 'node' ? { start: ['node', 'server.mjs'], healthPath: '/' } : { spa: false }),
+    };
+    await writeFile(join(target, 'agentdock.json'), JSON.stringify(config, null, 2) + '\n', {
+      flag: 'wx',
+    });
+    return { path: join(target, 'agentdock.json'), config };
+  }
+  const endpoint = (flags.url ?? process.env.AGENTDOCK_URL ?? 'http://127.0.0.1:4400').replace(
+    /\/$/,
+    '',
+  );
+  let token = process.env.AGENTDOCK_TOKEN;
+  if (!token && /^http:\/\/(127\.0\.0\.1|localhost):4400$/.test(endpoint)) {
+    try {
+      token = (
+        await readFile(new URL('../.agentdock/admin-token', import.meta.url), 'utf8')
+      ).trim();
+    } catch {}
+  }
+  if (!token) throw new Error('请设置 AGENTDOCK_TOKEN');
+  async function api(path, method = 'GET', body, key) {
+    const response = await fetch(endpoint + '/api' + path, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...(key ? { 'Idempotency-Key': key } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(30000),
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      const e = new Error(data.error?.message ?? response.statusText);
+      e.code = data.error?.code;
+      throw e;
+    }
+    return data;
+  }
+  if (command === 'projects') return api('/projects');
+  if (['resources', 'create-kv', 'create-bucket', 'create-database'].includes(command)) {
+    if (!positional[0]) throw new Error('需要项目 ID');
+    const base = '/projects/' + encodeURIComponent(positional[0]);
+    if (command === 'resources') return api(base + '/resources');
+    if (command === 'create-database') return api(base + '/database', 'POST', {});
+    if (!flags.name) throw new Error('需要 --name');
+    return api(base + (command === 'create-kv' ? '/kv' : '/buckets'), 'POST', { name: flags.name });
+  }
+  if (command === 'cancel') {
+    if (!positional[0]) throw new Error('需要部署 ID');
+    return api(`/deployments/${encodeURIComponent(positional[0])}/cancel`, 'POST', {});
+  }
+  if (command === 'prune') {
+    if (!positional[0]) throw new Error('需要项目 ID');
+    return api(`/projects/${encodeURIComponent(positional[0])}/prune`, 'POST', {
+      keep: Number(flags.keep ?? 5),
+    });
+  }
+  if (command === 'status' || command === 'logs') {
+    if (!positional[0]) throw new Error('需要部署 ID');
+    return api(
+      `/deployments/${encodeURIComponent(positional[0])}${command === 'logs' ? '/logs' : ''}`,
+    );
+  }
+  if (command === 'promote') {
+    if (positional.length !== 2) throw new Error('需要项目 ID 和部署 ID');
+    return api(`/projects/${encodeURIComponent(positional[0])}/promote`, 'POST', {
+      deploymentId: positional[1],
+    });
+  }
+  if (command === 'env') {
+    if (!positional[0] || !flags.file) throw new Error('需要项目 ID 和 --file variables.json');
+    return api(`/projects/${encodeURIComponent(positional[0])}/env`, 'PUT', {
+      values: JSON.parse(await readFile(resolve(flags.file), 'utf8')),
+    });
+  }
+  if (command !== 'deploy') throw new Error(`未知命令：${command}`);
+  const base = resolve(positional[0] ?? '.');
+  let config = {};
+  try {
+    config = JSON.parse(await readFile(join(base, 'agentdock.json'), 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const slug = flags.project ?? config.project;
+  if (!slug) throw new Error('请指定 --project 或在 agentdock.json 中设置 project');
+  const kind = flags.kind ?? config.kind ?? 'static';
+  const files = await collectFiles(resolve(base, config.directory ?? '.'));
+  let project = (await api('/projects')).data.find((p) => p.slug === slug);
+  if (!project) {
+    try {
+      project = await api('/projects', 'POST', { name: slug, slug });
+    } catch (error) {
+      if (error.code !== 'SLUG_TAKEN') throw error;
+      project = (await api('/projects')).data.find((p) => p.slug === slug);
+    }
+  }
+  const body = {
+    kind,
+    files,
+    resources:
+      flags['no-resources'] === true
+        ? false
+        : flags.resources === true
+          ? true
+          : (config.resources ?? kind === 'node'),
+    resourceScopes: flags['resource-scopes']
+      ? flags['resource-scopes'].split(',').filter(Boolean)
+      : config.resourceScopes,
+    spa: flags.spa || config.spa || false,
+    build: flags.build || config.build || false,
+    start: config.start ?? ['node', 'server.mjs'],
+    healthPath: config.healthPath ?? '/',
+    entry: flags.entry ?? config.entry,
+    assets: flags.assets ?? config.assets,
+    compatibilityDate: config.compatibilityDate,
+  };
+  let result = await api(
+    `/projects/${project.id}/deployments`,
+    'POST',
+    body,
+    flags.key ?? randomUUID(),
+  );
+  if (flags['no-wait']) return result;
+  const deadline = Date.now() + 300000;
+  while (!['ready', 'failed', 'cancelled', 'deleted'].includes(result.status)) {
+    if (Date.now() > deadline) {
+      const error = new Error(`等待超时，部署仍可能继续。请执行 agentdock status ${result.id}`);
+      error.code = 'WAIT_TIMEOUT';
+      throw error;
+    }
+    await new Promise((r) => setTimeout(r, 750));
+    result = await api(`/deployments/${result.id}`);
+  }
+  if (result.status !== 'ready') {
+    const error = new Error(result.error ?? `部署状态：${result.status}`);
+    error.code = 'DEPLOYMENT_FAILED';
+    error.deploymentId = result.id;
+    throw error;
+  }
+  return result;
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((error) => {
+      console.error(
+        JSON.stringify(
+          {
+            error: {
+              code: error.code ?? 'CLI_ERROR',
+              message: error.message,
+              deploymentId: error.deploymentId,
+            },
+          },
+          null,
+          2,
+        ),
+      );
+      process.exitCode = 1;
+    });
+}

package/mcp/api.mjs

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+export async function platformApi(path, method = 'GET', body) {
+  const endpoint = (process.env.AGENTDOCK_URL ?? 'http://127.0.0.1:4400').replace(/\/$/, '');
+  let token = process.env.AGENTDOCK_TOKEN;
+  if (!token && /^http:\/\/(127\.0\.0\.1|localhost):4400$/.test(endpoint)) {
+    try {
+      token = (
+        await readFile(new URL('../.agentdock/admin-token', import.meta.url), 'utf8')
+      ).trim();
+    } catch {}
+  }
+  if (!token) throw new Error('请设置 AGENTDOCK_TOKEN');
+  const r = await fetch(endpoint + '/api' + path, {
+    method,
+    headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(30000),
+  });
+  const data = await r.json();
+  if (!r.ok) {
+    const e = new Error(data.error?.message ?? '请求失败');
+    e.code = data.error?.code;
+    throw e;
+  }
+  return data;
+}

package/mcp/index.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { main } from '../cli/index.mjs';
+import { registerResourceTools } from './resource-tools.mjs';
+import { registerProjectTools } from './project-tools.mjs';
+import { platformApi } from './api.mjs';
+import { saveLocalBinding } from './local-development.mjs';
+const server = new McpServer({ name: 'agentdock', version: '0.2.0' });
+const tool = (name, description, inputSchema, fn, readOnlyHint = false) =>
+  server.registerTool(
+    name,
+    {
+      description,
+      inputSchema,
+      annotations: { readOnlyHint, destructiveHint: !readOnlyHint, idempotentHint: readOnlyHint },
+    },
+    async (args) => {
+      try {
+        return { content: [{ type: 'text', text: JSON.stringify(await fn(args)) }] };
+      } catch (e) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ error: { code: e.code ?? 'MCP_ERROR', message: e.message } }),
+            },
+          ],
+        };
+      }
+    },
+  );
+tool('list_projects', '列出当前令牌可访问的项目', {}, () => main(['projects']), true);
+registerProjectTools(tool, platformApi);
+tool(
+  'list_resources',
+  '列出项目的 KV、数据库和 OSS 资源',
+  { projectId: z.string() },
+  (a) => main(['resources', a.projectId]),
+  true,
+);
+tool(
+  'deploy_site',
+  '从本地目录上传静态、Node.js 或 Worker 应用，异步返回部署 ID。需轮询状态确认 ready。Node.js App 默认启用项目资源绑定。开发服务端代码时安装 @co-villa/agentnest-sdk 并使用 createClient()，平台自动注入访问配置；不要让用户手动生成资源令牌，不要将部署令牌作为应用资源令牌。资源需先通过 MCP 创建，数据库轮询到 ready；resources:false 可显式关闭绑定。本地开发先调用 prepare_local_development 并自动保存绑定，再使用 createClient()；不要让用户配置 AGENTDOCK_URL/AGENTDOCK_TOKEN 或生成资源令牌。',
+  {
+    directory: z.string(),
+    project: z.string(),
+    kind: z.enum(['static', 'node', 'worker']),
+    entry: z.string().optional(),
+    assets: z.string().optional(),
+    spa: z.boolean().optional(),
+    build: z.boolean().optional(),
+    resources: z.boolean().optional(),
+    resourceScopes: z
+      .array(z.enum(['kv:read', 'kv:write', 'oss:read', 'oss:write', 'db:query']))
+      .optional(),
+    idempotencyKey: z.string(),
+  },
+  (a) =>
+    main([
+      'deploy',
+      a.directory,
+      '--project',
+      a.project,
+      '--kind',
+      a.kind,
+      '--key',
+      a.idempotencyKey,
+      '--no-wait',
+      ...(a.entry ? ['--entry', a.entry] : []),
+      ...(a.assets ? ['--assets', a.assets] : []),
+      ...(a.spa ? ['--spa'] : []),
+      ...(a.build ? ['--build'] : []),
+      ...(a.resources === false ? ['--no-resources'] : a.resources ? ['--resources'] : []),
+      ...(a.resourceScopes ? ['--resource-scopes', a.resourceScopes.join(',')] : []),
+    ]),
+);
+tool(
+  'get_deployment',
+  '读取部署状态与访问 URL',
+  { deploymentId: z.string() },
+  (a) => main(['status', a.deploymentId]),
+  true,
+);
+tool(
+  'get_logs',
+  '读取构建及运行日志',
+  { deploymentId: z.string() },
+  (a) => main(['logs', a.deploymentId]),
+  true,
+);
+tool(
+  'promote_deployment',
+  '将项目线上版本切换为指定成功版本',
+  { projectId: z.string(), deploymentId: z.string() },
+  (a) => main(['promote', a.projectId, a.deploymentId]),
+);
+tool('cancel_deployment', '取消尚未完成的部署', { deploymentId: z.string() }, (a) =>
+  main(['cancel', a.deploymentId]),
+);
+registerResourceTools(tool, platformApi, { saveLocalBinding });
+await server.connect(new StdioServerTransport());

package/mcp/local-development.mjs

@@ -0,0 +1,43 @@
+import { mkdir, readFile, writeFile, lstat } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+export async function saveLocalBinding(binding, directory) {
+  const root = resolve(directory),
+    folder = join(root, '.agentdock');
+  try {
+    if ((await lstat(folder)).isSymbolicLink())
+      throw new Error('Development binding directory must not be a symlink');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  await mkdir(folder, { recursive: true, mode: 0o700 });
+  const target = join(folder, 'development.json');
+  try {
+    if ((await lstat(target)).isSymbolicLink())
+      throw new Error('Development binding file must not be a symlink');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  await writeFile(target, JSON.stringify(binding.config, null, 2) + '\n', { mode: 0o600 });
+  const ignore = join(root, '.gitignore');
+  let text = '';
+  try {
+    text = await readFile(ignore, 'utf8');
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (
+    !text
+      .split(/\r?\n/)
+      .some((line) => ['.agentdock/', '/.agentdock/', '.agentdock'].includes(line.trim()))
+  )
+    await writeFile(ignore, text + (text && !text.endsWith('\n') ? '\n' : '') + '.agentdock/\n');
+  return {
+    projectId: binding.config.projectId,
+    project: binding.config.project,
+    file: target,
+    expiresAt: binding.config.expiresAt,
+    ready: true,
+    instructions:
+      '本地绑定已自动保存，直接运行使用 createClient() 的 App。无需设置 AGENTDOCK_URL 或 AGENTDOCK_TOKEN。',
+  };
+}

package/mcp/project-tools.mjs

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+
+export function registerProjectTools(tool, api) {
+  const id = z.string().min(1);
+  tool(
+    'create_project',
+    '创建项目，需要账号范围的 manage 授权；项目数量仍受账号配额限制',
+    {
+      name: id.max(80),
+      slug: id,
+      organizationId: id.optional(),
+    },
+    (a) => api('/projects', 'POST', a),
+  );
+  tool(
+    'get_project',
+    '查看项目配置、环境变量名称和运行状态',
+    { projectId: id },
+    (a) => api(`/projects/${encodeURIComponent(a.projectId)}`),
+    true,
+  );
+  tool(
+    'update_project',
+    '修改项目名称或关联组织，需要 manage 授权和项目所有者权限；organizationId 为 null 时解除关联',
+    {
+      projectId: id,
+      name: id.max(80).optional(),
+      organizationId: id.nullable().optional(),
+    },
+    ({ projectId, ...body }) => api(`/projects/${encodeURIComponent(projectId)}`, 'PATCH', body),
+  );
+  tool(
+    'set_project_environment',
+    '设置项目环境变量（完整替换），用于后续部署；需要 manage 授权和项目所有者权限。先通过 get_project 检查已有变量名称',
+    {
+      projectId: id,
+      values: z.record(z.string(), z.string()),
+    },
+    ({ projectId, values }) =>
+      api(`/projects/${encodeURIComponent(projectId)}/env`, 'PUT', { values }),
+  );
+  tool(
+    'set_project_scaling',
+    '配置 Kubernetes 应用副本与 CPU 扩缩容目标，需要 manage 授权和项目所有者权限',
+    {
+      projectId: id,
+      min: z.number().int().min(1).max(20),
+      max: z.number().int().min(1).max(20),
+      cpu: z.number().int().min(10).max(90),
+    },
+    ({ projectId, ...body }) =>
+      api(`/projects/${encodeURIComponent(projectId)}/scale`, 'POST', body),
+  );
+}

package/mcp/resource-tools.mjs

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+// Shared registrations for remote HTTP and packaged stdio MCP; API remains the authority.
+export function registerResourceTools(tool, api, { saveLocalBinding } = {}) {
+  const id = z.string().min(1),
+    project = { projectId: id },
+    enc = encodeURIComponent;
+  const base = (a) => `/projects/${enc(a.projectId)}`;
+  tool(
+    'prepare_local_development',
+    'Agent 在本地启动 App 前默认自动调用本工具，复用当前 MCP 项目授权准备开发。Agent 必须自动将返回的 config 写入 App 根目录 .agentdock/development.json，并确保 .agentdock/ 被 git 忽略。不要让用户复制令牌或手动设置 AGENTDOCK_URL/AGENTDOCK_TOKEN。本地 SDK 使用 createClient() 自动读取并续期。绑定24小时有效，不包含 MCP 原始 OAuth 凭据。',
+    { ...project, ...(saveLocalBinding ? { directory: z.string().optional() } : {}) },
+    async (a) => {
+      const binding = await api(base(a) + '/local-development', 'POST', {});
+      return saveLocalBinding ? saveLocalBinding(binding, a.directory ?? '.') : binding;
+    },
+  );
+  const kv = (a) => `${base(a)}/kv/${enc(a.namespace)}`;
+  const bucket = (a) => `${base(a)}/buckets/${enc(a.bucketId)}`;
+  tool(
+    'get_database',
+    '查看项目数据库状态、模式与连接地址，不返回密码',
+    project,
+    (a) => api(base(a) + '/database'),
+    true,
+  );
+  tool(
+    'create_database',
+    '创建共享服务中的独立项目数据库和账号。异步返回；调用 get_database 等待 ready。部署权限可用，专属付费实例尚未开放。',
+    project,
+    (a) => api(base(a) + '/database', 'POST', { mode: 'shared' }),
+  );
+  tool(
+    'query_database',
+    '在项目数据库执行参数化 SQL。最多 1000 行 / 1 MiB，超时 5 秒；可能修改数据，需要部署权限。',
+    {
+      ...project,
+      sql: z.string().min(1).max(32768),
+      params: z.array(z.unknown()).max(100).optional(),
+    },
+    (a) => api(base(a) + '/database/query', 'POST', { sql: a.sql, params: a.params ?? [] }),
+  );
+  tool(
+    'get_database_credentials',
+    '返回项目数据库连接密码，仅项目所有者完整身份可用，部署 Token 不可用。不要将凭证写入公开代码或日志。',
+    project,
+    (a) => api(base(a) + '/database/credentials', 'POST', {}),
+    true,
+  );
+  tool(
+    'delete_database',
+    '永久删除项目数据库，需要所有者身份；confirm 必须等于项目 slug。',
+    { ...project, confirm: id },
+    (a) => api(base(a) + '/database', 'DELETE', { confirm: a.confirm }),
+  );
+  tool(
+    'list_kv_namespaces',
+    '列出当前项目 KV 命名空间',
+    project,
+    (a) => api(base(a) + '/kv'),
+    true,
+  );
+  tool(
+    'create_kv_namespace',
+    '创建项目 KV 命名空间，需要部署权限',
+    { ...project, name: z.string().regex(/^[a-z][a-z0-9_-]{0,39}$/) },
+    (a) => api(base(a) + '/kv', 'POST', { name: a.name }),
+  );
+  tool(
+    'delete_kv_namespace',
+    '永久删除命名空间及所有键，需要项目所有者身份和名称确认',
+    { ...project, namespace: id, confirm: id },
+    (a) => api(kv(a), 'DELETE', { confirm: a.confirm }),
+  );
+  tool(
+    'list_kv_entries',
+    '分页列出 KV 键；返回 cursor，下一页作为 after 传入',
+    { ...project, namespace: id, prefix: z.string().optional(), after: z.string().optional() },
+    (a) => {
+      const q = new URLSearchParams();
+      if (a.prefix !== undefined) q.set('prefix', a.prefix);
+      if (a.after !== undefined) q.set('after', a.after);
+      return api(kv(a) + '/entries?' + q);
+    },
+    true,
+  );
+  tool(
+    'get_kv_entry',
+    '读取项目 KV JSON 值和过期时间',
+    { ...project, namespace: id, key: id },
+    (a) => api(kv(a) + '/entries/' + enc(a.key)),
+    true,
+  );
+  tool(
+    'put_kv_entry',
+    '写入 KV JSON 值，ttl 为秒，省略表示永久；需要部署权限',
+    {
+      ...project,
+      namespace: id,
+      key: id,
+      value: z.unknown(),
+      ttl: z.number().int().min(1).max(31536000).optional(),
+    },
+    (a) =>
+      api(kv(a) + '/entries/' + enc(a.key), 'PUT', {
+        value: a.value,
+        ...(a.ttl === undefined ? {} : { ttl: a.ttl }),
+      }),
+  );
+  tool(
+    'delete_kv_entry',
+    '删除项目 KV 键，需要部署权限',
+    { ...project, namespace: id, key: id },
+    (a) => api(kv(a) + '/entries/' + enc(a.key), 'DELETE'),
+  );
+  tool(
+    'list_storage_buckets',
+    '列出项目 OSS 存储桶及用量',
+    project,
+    (a) => api(base(a) + '/buckets'),
+    true,
+  );
+  tool(
+    'create_storage_bucket',
+    '创建私有 OSS 存储桶，需要部署权限',
+    { ...project, name: z.string().regex(/^[a-z][a-z0-9-]{2,39}$/) },
+    (a) => api(base(a) + '/buckets', 'POST', { name: a.name }),
+  );
+  tool(
+    'delete_storage_bucket',
+    '删除空存储桶，需要项目所有者身份；非空桶拒绝删除',
+    { ...project, bucketId: id },
+    (a) => api(bucket(a), 'DELETE'),
+  );
+  tool(
+    'list_storage_objects',
+    '列出项目 OSS 存储桶对象',
+    { ...project, bucketId: id },
+    (a) => api(bucket(a) + '/objects'),
+    true,
+  );
+  tool(
+    'put_storage_object',
+    '上传 OSS 文件，content 为 Base64，文件最多 10 MiB，需要部署权限',
+    { ...project, bucketId: id, name: id, content: z.string().max(14 * 1024 * 1024) },
+    (a) => api(bucket(a) + '/objects', 'POST', { name: a.name, content: a.content }),
+  );
+  tool(
+    'sign_storage_object',
+    '生成对象限时下载链接，链接包含临时授权，请勿公开',
+    {
+      ...project,
+      bucketId: id,
+      objectId: id,
+      seconds: z.number().int().min(1).max(3600).optional(),
+    },
+    (a) =>
+      api(bucket(a) + '/sign', 'POST', {
+        objectId: a.objectId,
+        ...(a.seconds === undefined ? {} : { seconds: a.seconds }),
+      }),
+    true,
+  );
+  tool(
+    'delete_storage_object',
+    '删除 OSS 对象，需要部署权限',
+    { ...project, bucketId: id, objectId: id },
+    (a) => api(bucket(a) + '/objects/' + enc(a.objectId), 'DELETE'),
+  );
+  tool(
+    'list_domains',
+    '列出 App 自定义域名、TXT 验证记录及验证状态',
+    project,
+    (a) => api(base(a) + '/domains'),
+    true,
+  );
+  tool(
+    'add_domain',
+    '绑定 App 域名并生成 TXT 验证记录，需要项目所有者身份',
+    { ...project, hostname: id },
+    (a) => api(base(a) + '/domains', 'POST', { hostname: a.hostname }),
+  );
+  tool(
+    'verify_domain',
+    '验证 App 域名的 DNS TXT 所有权，需要项目所有者身份；仅验证成功后启用路由',
+    { ...project, hostname: id },
+    (a) => api(base(a) + '/domains/verify', 'POST', { hostname: a.hostname }),
+  );
+  tool(
+    'remove_domain',
+    '解绑 App 自定义域名，需要项目所有者身份',
+    { ...project, hostname: id },
+    (a) => api(base(a) + '/domains/' + enc(a.hostname), 'DELETE'),
+  );
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@co-villa/agentnest-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "description": "AgentNest deployment CLI and MCP stdio server",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "cli/index.mjs",
+    "mcp/index.mjs",
+    "mcp/resource-tools.mjs",
+    "mcp/project-tools.mjs",
+    "mcp/api.mjs",
+    "mcp/local-development.mjs"
+  ],
+  "bin": {
+    "agentnest": "./cli/index.mjs",
+    "agentnest-mcp": "./mcp/index.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  }
 }