{"_id":"@astonous-360/astonous-360","name":"@astonous-360/astonous-360","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.2":{"name":"@astonous-360/astonous-360","version":"0.1.2","description":"Astonous 360 MCP server for Salesforce projects (Python backend, npm-distributed)","license":"MIT","bin":{"salesforce-mcp":"bin/cli.js","astonous-360-mcp":"bin/cli.js","codex-sf-kit":"bin/codex-sf-kit.js"},"engines":{"node":">=18"},"scripts":{"mcp:install":"bash ./setup-astonous-360.sh .","mcp:doctor":"node ./bin/codex-sf-kit.js doctor --project-root ."},"_id":"@astonous-360/astonous-360@0.1.2","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-aIovUZvnwkKd5jadKXrkOv1I+9hv+TgSYIowQAm65ij/CBRc3xzxgz7M16qST1g2fCP+kwRnwnpOUL6WwSIUHw==","shasum":"307879944cf92b20d595446655429c8b6e810747","tarball":"https://registry.npmjs.org/@astonous-360/astonous-360/-/astonous-360-0.1.2.tgz","fileCount":28,"unpackedSize":347402,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDegRZPmIkPiL4/LO5JVECT3bV9wTMlFIest6c1aDUVsAIgESYsTuQvtwRCpIWRskoq9edOf3XdypbFD3nGtMC2p6I="}]},"_npmUser":{"name":"ritikjain30","email":"ritik.jain@astonous.com"},"directories":{},"maintainers":[{"name":"ritikjain30","email":"ritik.jain@astonous.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/astonous-360_0.1.2_1779644549133_0.3020969466879486"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-24T17:42:28.992Z","0.1.2":"2026-05-24T17:42:29.286Z","modified":"2026-05-24T17:42:29.476Z"},"maintainers":[{"name":"ritikjain30","email":"ritik.jain@astonous.com"}],"description":"Astonous 360 MCP server for Salesforce projects (Python backend, npm-distributed)","license":"MIT","readme":"# Astonous 360 MCP Server (Python, npm distributed)\n\nThis repository provides a Python-based MCP server for Salesforce projects, distributed as an npm package so it can be installed globally and used in any Salesforce folder.\n\n## Features\n\n- Detect Salesforce project roots (`sfdx-project.json`).\n- Read project metadata (package.xml, Apex, LWC, Aura).\n- Search repo files.\n- Run Salesforce CLI commands for orgs, queries, Apex execution, tests, deploy/retrieve, logs.\n- Generic `sf_cli` tool for full Salesforce CLI coverage.\n\n## Requirements\n\n- Node.js 18+\n- Python 3.10+\n- Salesforce CLI (`sf` on PATH)\n- Python package `fastmcp` installed (`python -m pip install fastmcp`)\n\n## Install (npm, global)\n\n```bash\nnpm install -g @astonous/astonous-360\n```\n\nFrom a checkout of this repo, you can run one install command:\n\n```bash\nnpm run mcp:install\n```\n\n## Team Bootstrap (Codex + MCP)\n\nAfter installing, run this in any Salesforce project root:\n\n```bash\ncodex-sf-kit init --project-root .\n```\n\nYou can configure multiple project folders in one command:\n\n```bash\ncodex-sf-kit init /path/to/project-a /path/to/project-b --skip-install\n```\n\nOr run the full environment bootstrap script from this repo checkout:\n\n```bash\n./setup-astonous-360.sh /path/to/salesforce-project\n```\n\nThis configures:\n- `~/.zshrc` PATH for user npm globals\n- Python 3.11 + `fastmcp`\n- `SALESFORCE_MCP_PYTHON`\n- project `.vscode/mcp.json`\n- project `.codex/config.toml` Salesforce MCP block\n\nVerify setup:\n\n```bash\ncodex-sf-kit doctor --project-root .\n```\n\nExpected output includes:\n- `salesforce-mcp: ok`\n- `.vscode/mcp.json: ok`\n- `.codex/config.toml: ok`\n\nIf you see `salesforce-mcp: missing`:\n\n```bash\nnpm run mcp:install\nwhich salesforce-mcp\n```\n\nIf `which salesforce-mcp` is empty, add your npm global bin to PATH (zsh):\n\n```bash\necho 'export PATH=\"$(npm config get prefix)/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n## VS Code MCP Configuration\n\nVS Code MCP servers can be configured in user/workspace settings. Examples from MCP server docs show `mcp.servers` in `settings.json`, or a `.vscode/mcp.json` file with `servers` entries.\n\n### Option A: User or workspace settings\n\n```json\n{\n  \"mcp.servers\": {\n    \"salesforce\": {\n      \"type\": \"stdio\",\n      \"command\": \"salesforce-mcp\",\n      \"args\": [\"--project-root\", \"${workspaceFolder}\"]\n    }\n  }\n}\n```\n\n### Option B: Workspace file `.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"salesforce\": {\n      \"type\": \"stdio\",\n      \"command\": \"salesforce-mcp\",\n      \"args\": [\"--project-root\", \"${workspaceFolder}\"]\n    }\n  }\n}\n```\n\nIf your VS Code MCP client prefers `mcp.servers` as a list instead of a map, adapt accordingly (some MCP server docs show list form).\n\n## Environment Variables\n\n- `SF_MCP_PROJECT_ROOT`: Force a project root if auto-detection doesn’t find it.\n- `SF_MCP_OS360_ACTION_SPEC_PATH`: Optional path to OS action catalog spec JSON (relative to project root or absolute). Default: `scripts/astonous-360/docs/OS_V1_ACTION_CATALOG.json`.\n- `SALESFORCE_MCP_PYTHON`: Override the Python executable used by the npm wrapper.\n- `SF_MCP_STANDARDS_PATH`: Optional path to a standards JSON file (relative to project root or absolute).\n- `SF_MCP_DOCS_DIR`: Optional path to docs/standards knowledge directory used by `docs_*` tools.\n- `SF_MCP_COMMAND_TIMEOUT_SECONDS`: Default subprocess timeout in seconds for CLI-backed tools (default `300`).\n- `SF_MCP_COMMAND_RETRIES`: Retry count for retryable CLI failures/timeouts (default `1`).\n- `SF_MCP_MAX_OUTPUT_CHARS`: Max command output retained in responses/errors (default `20000`).\n- `SF_MCP_SF_CLI_WINDOW_SECONDS`: `sf_cli` rate-limit window size in seconds (default `60`).\n- `SF_MCP_SF_CLI_MAX_CALLS`: Max `sf_cli` calls allowed per rate-limit window (default `20`).\n- `SF_MCP_SF_CLI_MAX_ARGS`: Max number of args accepted by `sf_cli` (default `80`).\n- `SF_MCP_SF_CLI_MAX_ARG_LENGTH`: Max length per `sf_cli` arg (default `512`).\n- `SF_MCP_ALLOW_DANGEROUS_SF_CLI`: Set to `1`/`true`/`yes` to allow blocked high-risk `sf_cli` prefixes (plugins install/uninstall/link, update, org delete, data delete).\n- `JIRA_BASE_URL`: Jira Cloud base URL, e.g. `https://yourcompany.atlassian.net`.\n- `JIRA_EMAIL`: Jira user email for API token auth.\n- `JIRA_API_TOKEN`: Jira API token for basic auth.\n- `JIRA_BEARER_TOKEN`: Optional bearer token (if your org uses OAuth).\n- `ASTONOUS_IMPLEMENT_COMMAND`: Optional shell command used by ticket workflow implementation stage. Supports `{issue_key}`, `{project_root}`, `{context_file}` placeholders.\n- `ASTONOUS_PROCESS_TIMEOUT_SECONDS`: Timeout for workflow internal subprocesses like `git`/`gh` (default `120`).\n- `ASTONOUS_IMPLEMENTATION_TIMEOUT_SECONDS`: Timeout for workflow implementation command execution (default `1800`).\n- `ASTONOUS_DEFAULT_TARGET_ORG`: Fallback Salesforce org alias for ticket workflows.\n- `ASTONOUS_ORG_ROUTING_RULES`: JSON array of routing rules. Example: `[{\"project_key\":\"HEB\",\"issue_type\":\"Bug\",\"target_org\":\"IPD UAT\"}]`.\n- `ASTONOUS_POST_DEPLOY_SOQL`: JSON array of post-deploy verification SOQL queries.\n\n## Jira Setup (Cloud)\n\n```bash\nexport JIRA_BASE_URL=\"https://yourcompany.atlassian.net\"\nexport JIRA_EMAIL=\"you@yourcompany.com\"\nexport JIRA_API_TOKEN=\"<token>\"\n```\n\nIf env vars are not present, Jira credentials are also read from `.codex/config.toml`:\n\n```toml\n[mcp_servers.salesforce.env]\nJIRA_BASE_URL = \"https://yourcompany.atlassian.net\"\nJIRA_EMAIL = \"you@yourcompany.com\"\nJIRA_API_TOKEN = \"<token>\"\n```\n\n## Tools Provided (high level)\n\n- `project_root`, `project_info`\n- `list_apex_classes`, `list_lwc_components`, `list_aura_components`, `list_package_xml`\n- `read_file`, `search_repo`\n- `docs_list`, `docs_search`, `docs_read` (Astonous 360 `Documents/` knowledge folder)\n- `sf_org_list`, `sf_org_list_auth`, `sf_data_query`\n- `sf_apex_run`, `sf_apex_run_test`, `sf_apex_get_test`\n- `sf_project_deploy`, `sf_project_retrieve`\n- `sf_apex_logs_list`, `sf_apex_logs_get`\n- `sf_cli` (generic Salesforce CLI wrapper)\n- `standards_get`, `standards_validate_name`\n- `standards_generate_apex_class`, `standards_generate_apex_test_class`\n- `standards_scan_repo`\n- `standards_scan_apexdoc`, `standards_scan_soql_in_loops`\n- `standards_suggest_flow_name`, `standards_scan_lwc_naming`\n- `jira_myself`\n- `jira_search_issues`, `jira_get_issue`\n- `jira_create_issue`, `jira_update_issue_fields`, `jira_add_comment`\n- `jira_list_transitions`, `jira_transition_issue`, `jira_transition_issue_by_name`\n- `jira_list_projects`\n- `jira_list_issue_types`\n- `jira_get_create_meta`\n- `jira_run_ticket_workflow`, `jira_get_ticket_workflow_run`\n- `jira_run_ticket_batch_workflow`, `jira_run_ticket_batch_from_jql`, `jira_get_ticket_batch_workflow_run`\n- `os360_get_reference_architecture`\n- `os360_list_action_catalog`, `os360_plan_actions`\n- `os360_request_approval`, `os360_decide_approval`\n- `os360_execute_action`, `os360_get_action_run`\n\nExample implementation command:\n\n```bash\nexport ASTONOUS_IMPLEMENT_COMMAND='codex exec \"Implement Jira {issue_key} for Salesforce project at {project_root}. Use context from {context_file}. Make code changes, then run tests.\"'\n```\n\nExample workflow run with commit + PR automation:\n\n```text\njira_run_ticket_workflow(\n  issue_key=\"SOCK-123\",\n  mode=\"execute\",\n  target_org=\"my-sandbox\",\n  allowed_write_globs=[\"force-app/**\", \"manifest/**\"],\n  auto_commit=True,\n  auto_pr=True\n)\n```\n\nExample manager-style batch run (one PR per ticket):\n\n```text\njira_run_ticket_batch_from_jql(\n  jql=\"project = SOCK AND assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC\",\n  mode=\"execute\",\n  target_org=\"my-sandbox\",\n  implementation_command='codex exec \"Implement {issue_key} for {project_root} using {context_file}. Run tests and open PR.\"',\n  allowed_write_globs=[\"force-app/**\", \"manifest/**\"],\n  auto_commit=True,\n  auto_pr=True,\n  continue_on_error=True\n)\n```\n\nYou can poll the batch later:\n\n```text\njira_get_ticket_batch_workflow_run(batch_id=\"batch_20260524xxxxxx_ab12cd34\")\n```\n\nNotes:\n- `auto_pr=True` requires `gh` CLI installed and authenticated.\n- Auto-commit stages only files changed during this workflow run.\n- OS-v1 reference docs are in `docs/OS_V1_ARCHITECTURE.md` and `docs/OS_V1_CONTROL_PLANE_OPENAPI.yaml`.\n- Salesforce workflow now supports org-aware routing, safe deploy (`--dry-run` + deploy), and post-deploy verification checks.\n\nFlow naming enforced by standards tools:\n- Record-triggered: `Automation - Object Name - Functionality`\n- Screen: `Interface - Object Name - Functionality` (requires `recordId` input variable of record type)\n- Autolaunched: `Autolaunched - Object Name - Functionality`\n- Scheduled: `Scheduled - Object Name - Functionality`\n\n## Local Development\n\n```bash\npython -m pip install -e .\npython -m salesforce_mcp.server --project-root /path/to/sfdx/project\n```\n\n## VS Code Extension Scaffold\n\nA starter VS Code extension is included here:\n\n- `vscode-extension/astonous-360-vscode`\n\nIt adds command-palette actions to run `codex-sf-kit init/doctor` for the active workspace or multiple projects.\n\n## Agent Prompt Template\n\nReusable Salesforce-only system prompt for your custom coding agent:\n\n- `agents/ASTONOUS_DEVELOPER_AGENT.md`\n\n## Project Knowledge Documents\n\nYou can store API/business docs in:\n\n- `Astonous-360/Documents/` (preferred in this repo layout)\n- `scripts/astonous-360/Documents/` (when Astonous 360 is used as a submodule in `scripts/`)\n- `Astonous-360/Standards/` (development standards/playbooks)\n- `scripts/astonous-360/Standards/` (submodule layout)\n\nThe MCP server exposes:\n\n- `docs_list`\n- `docs_search`\n- `docs_read`\n\nUse these before implementation so generated code follows your uploaded docs.\n\n## Publishing to npm\n\n1. Update `package.json` name/version/description.\n2. `npm publish --access public`\n\n## Notes\n\n- The npm package bundles the Python source but does not install Python deps. Install `fastmcp` via pip on any machine running the server.\n- Ensure `sf` CLI is installed and authenticated.\n","readmeFilename":"README.md","_rev":"1-eca0a31bd5fa8947d89664da7347d179"}